Manipulação Global de Eventos e Muito Mais

Ao construir aplicações web sofisticadas, chega um momento em que os limites precisos da manipulação de eventos no escopo do componente simplesmente não são suficientes. Você precisa responder a um atalho de teclado pressionado em qualquer lugar da página.

Você precisa detectar quando os usuários clicam fora de um menu suspenso. Você precisa coordenar operações de arrastar e soltar que abrangem toda a viewport. Esses cenários exigem acesso a eventos no nível do body do documento, e o Svelte 5 oferece uma solução elegante e declarativa por meio do elemento especial <svelte:body>.

Este tutorial explora as profundezas do <svelte:body>, examinando não apenas como utilizá-lo, mas por que ele existe, quando recorrer a ele e como arquitetar soluções robustas em torno da manipulação de eventos no body. Trabalharemos com exemplos progressivamente mais complexos, descobriremos armadilhas sutis que podem pegar até desenvolvedores experientes de surpresa e estabeleceremos padrões que escalam de forma elegante em aplicações do mundo real.

Entendendo o Espaço do Problema: Por Que os Eventos no Nível do Body São Importantes

Antes de mergulhar na sintaxe e na implementação, vamos estabelecer um entendimento claro de por que a manipulação de eventos no nível do body representa uma categoria distinta de problemas no desenvolvimento frontend.

Considere uma arquitetura típica baseada em componentes. Cada componente encapsula sua própria estrutura DOM, estilos e comportamento. Os manipuladores de eventos são anexados a elementos específicos dentro do template daquele componente. Esse modelo funciona muito bem para interações que ocorrem inteiramente dentro dos limites de um componente — clicar em um botão, digitar em um input, passar o mouse sobre um card.

Mas as aplicações web rotineiramente requerem interações que transcendem essas fronteiras. Imagine implementar um diálogo modal. O modal em si é um componente, talvez renderizado condicionalmente em algum lugar na sua árvore de componentes. Mas o comportamento esperado do usuário — pressionar Escape para fechar o modal, ou clicar no backdrop fora do conteúdo do modal — envolve eventos que podem se originar de elementos bem fora da subárvore DOM do componente modal.

A solução ingênua poderia envolver anexar ouvintes de eventos diretamente ao document.body dentro do ciclo de vida do seu componente:

// This works, but it's imperative and error-prone
import { onMount, onDestroy } from 'svelte'

let cleanup

onMount(() => {
	const handler = (event) => {
		if (event.key === 'Escape') {
			closeModal()
		}
	}
	document.body.addEventListener('keydown', handler)
	cleanup = () => document.body.removeEventListener('keydown', handler)
})

onDestroy(() => {
	cleanup?.()
})

Essa abordagem tem várias desvantagens. É imperativa em vez de declarativa, misturando gerenciamento de ciclo de vida com lógica de manipulação de eventos. Requer limpeza explícita para evitar vazamentos de memória. Não se integra naturalmente ao sistema de reatividade do Svelte. E espalha a lógica de manipulação de eventos por vários locais no seu código.

O elemento especial <svelte:body> aborda todas essas preocupações, fornecendo uma sintaxe declarativa que se integra perfeitamente ao modelo de componentes do Svelte e, no Svelte 5, ao sistema de reatividade baseado em runes.

A Anatomia do `<svelte:body>`

O elemento <svelte:body> é um dos vários elementos especiais que o Svelte oferece para interagir com partes do DOM que existem fora do template do seu componente. Ao contrário dos elementos regulares, <svelte:body> não renderiza nada no DOM — ele serve puramente como um ponto de anexo declarativo para ouvintes de eventos e ações no elemento document.body. Além dos manipuladores de eventos, você também pode usar a diretiva {@attach} (Svelte 5.29+) para anexar comportamentos diretamente ao elemento body.

No Svelte 5, os manipuladores de eventos usam a nova sintaxe de atributo on* em vez da sintaxe de diretiva on:* das versões anteriores. Aqui está a estrutura fundamental:

<script>
	function handleKeydown(event) {
		console.log('Key pressed:', event.key)
	}
</script>

<svelte:body onkeydown={handleKeydown} />

Quando este componente é montado, o Svelte anexa automaticamente o ouvinte de evento keydown ao document.body. Quando o componente é desmontado, o Svelte remove automaticamente o ouvinte. Esse gerenciamento automático de ciclo de vida elimina toda uma categoria de bugs relacionados a limpeza esquecida.

O elemento aceita qualquer manipulador de evento DOM válido como atributo. A convenção de nomenclatura segue o padrão de atributo HTML padrão: o nome do evento prefixado com on, tudo em minúsculas. Então keydown se torna onkeydown, mouseup se torna onmouseup, dragover se torna ondragover, e assim por diante.

Manipuladores Inline e Arrow Functions

Você pode definir manipuladores inline para operações simples:

<script>
	let lastKey = $state('')
</script>

<svelte:body onkeydown={(e) => (lastKey = e.key)} />

<p>Last key pressed: {lastKey || 'None yet'}</p>

Esse padrão funciona bem para atualizações de estado diretas, embora lógicas mais complexas geralmente se beneficiem de ser extraídas para funções nomeadas, visando legibilidade e testabilidade.

Múltiplos Manipuladores de Eventos

Um único elemento <svelte:body> pode anexar múltiplos manipuladores de eventos:

<script>
	let mousePosition = $state({ x: 0, y: 0 })
	let isMouseDown = $state(false)

	function trackMouse(event) {
		mousePosition = { x: event.clientX, y: event.clientY }
	}
</script>

<svelte:body
	onmousemove={trackMouse}
	onmousedown={() => (isMouseDown = true)}
	onmouseup={() => (isMouseDown = false)}
/>

<div class="tracker">
	Position: ({mousePosition.x}, {mousePosition.y})
	{#if isMouseDown}
		<span class="indicator">🖱️ Mouse button held</span>
	{/if}
</div>

Você também pode ter múltiplos elementos <svelte:body> em um único componente se isso melhorar a organização do código, embora consolidar manipuladores relacionados em um único elemento seja tipicamente mais limpo.

Mergulho Profundo

Construindo um Sistema de Atalhos de Teclado

Vamos construir um exemplo realista que demonstra o poder e as nuances do <svelte:body>. Construiremos um sistema de atalhos de teclado que suporta teclas modificadoras, evita conflitos com inputs de formulário e fornece feedback visual aos usuários.

<script>
	// Reactive state using Svelte 5 runes
	let shortcuts = $state([
		{ keys: ['Control', 's'], action: 'save', description: 'Save document' },
		{ keys: ['Control', 'Shift', 'p'], action: 'preview', description: 'Toggle preview' },
		{ keys: ['Escape'], action: 'close', description: 'Close dialog' },
		{ keys: ['Control', 'k'], action: 'search', description: 'Open search' }
	])

	let activeKeys = $state(new Set())
	let lastTriggeredAction = $state(null)
	let showShortcutHint = $state(false)

	// Derived state: compute which shortcut matches current key combination
	let matchingShortcut = $derived.by(() => {
		if (activeKeys.size === 0) return null

		return shortcuts.find((shortcut) => {
			if (shortcut.keys.length !== activeKeys.size) return false
			return shortcut.keys.every((key) => activeKeys.has(key))
		})
	})

	function shouldIgnoreEvent(event) {
		// Don't capture shortcuts when user is typing in form elements
		const target = event.target
		const tagName = target.tagName.toLowerCase()
		const isEditable = target.isContentEditable
		const isFormElement = ['input', 'textarea', 'select'].includes(tagName)

		// Exception: always allow Escape key
		if (event.key === 'Escape') return false

		return isEditable || isFormElement
	}

	function normalizeKey(event) {
		// Normalize modifier key names for cross-platform consistency
		if (event.key === 'Meta') return 'Control' // Treat Cmd as Ctrl on Mac
		return event.key
	}

	function handleKeydown(event) {
		if (shouldIgnoreEvent(event)) return

		const key = normalizeKey(event)

		// Create new Set to trigger reactivity
		activeKeys = new Set([...activeKeys, key])

		// Check if current combination matches a shortcut
		const matched = shortcuts.find((shortcut) => {
			if (shortcut.keys.length !== activeKeys.size) return false
			return shortcut.keys.every((k) => activeKeys.has(k))
		})

		if (matched) {
			event.preventDefault() // Prevent browser default behavior
			lastTriggeredAction = matched.action
			executeAction(matched.action)

			// Clear after short delay for visual feedback
			setTimeout(() => {
				lastTriggeredAction = null
			}, 1000)
		}
	}

	function handleKeyup(event) {
		const key = normalizeKey(event)

		// Create new Set without the released key
		const newKeys = new Set(activeKeys)
		newKeys.delete(key)
		activeKeys = newKeys
	}

	function executeAction(action) {
		// In a real application, these would trigger actual functionality
		console.log(`Executing action: ${action}`)

		switch (action) {
			case 'save':
				alert('Document saved!')
				break
			case 'preview':
				alert('Preview toggled!')
				break
			case 'close':
				alert('Dialog closed!')
				break
			case 'search':
				alert('Search opened!')
				break
		}
	}

	// Toggle shortcut hint overlay with ? key
	function handleQuestionMark(event) {
		if (event.key === '?' && !shouldIgnoreEvent(event)) {
			showShortcutHint = !showShortcutHint
		}
	}
</script>

<svelte:body onkeydown={handleKeydown} onkeyup={handleKeyup} onkeypress={handleQuestionMark} />

<div class="app-container">
	<header>
		<h1>Keyboard Shortcut Demo</h1>
		<p class="hint">Press <kbd>?</kbd> to view available shortcuts</p>
	</header>

	<main>
		<div class="status-panel">
			<h2>Current State</h2>
			<div class="active-keys">
				<strong>Active keys:</strong>
				{#if activeKeys.size > 0}
					{#each [...activeKeys] as key}
						<kbd>{key}</kbd>
					{/each}
				{:else}
					<span class="none">None</span>
				{/if}
			</div>

			{#if lastTriggeredAction}
				<div class="triggered-action">
					✓ Triggered: <strong>{lastTriggeredAction}</strong>
				</div>
			{/if}
		</div>

		<div class="test-area">
			<h2>Test Input (shortcuts disabled here)</h2>
			<input type="text" placeholder="Type here - shortcuts won't trigger" />
			<textarea placeholder="Or here - shortcuts won't trigger either"></textarea>
		</div>
	</main>

	{#if showShortcutHint}
		<div class="shortcut-overlay" role="dialog" aria-label="Keyboard shortcuts">
			<div class="shortcut-panel">
				<h2>Keyboard Shortcuts</h2>
				<ul>
					{#each shortcuts as shortcut}
						<li>
							<span class="keys">
								{#each shortcut.keys as key, i}
									<kbd>{key}</kbd>{#if i < shortcut.keys.length - 1}
										+
									{/if}
								{/each}
							</span>
							<span class="description">{shortcut.description}</span>
						</li>
					{/each}
				</ul>
				<button onclick={() => (showShortcutHint = false)}>Close (or press ?)</button>
			</div>
		</div>
	{/if}
</div>

<style>
	.app-container {
		font-family:
			system-ui,
			-apple-system,
			sans-serif;
		max-width: 800px;
		margin: 0 auto;
		padding: 2rem;
	}

	kbd {
		background: #e0e0e0;
		border: 1px solid #ccc;
		border-radius: 4px;
		padding: 0.2em 0.5em;
		font-family: monospace;
		font-size: 0.9em;
		margin: 0 0.2em;
	}

	.status-panel {
		background: #f5f5f5;
		padding: 1rem;
		border-radius: 8px;
		margin: 1rem 0;
	}

	.triggered-action {
		color: green;
		font-weight: bold;
		margin-top: 0.5rem;
	}

	.test-area input,
	.test-area textarea {
		display: block;
		width: 100%;
		padding: 0.5rem;
		margin: 0.5rem 0;
		border: 1px solid #ccc;
		border-radius: 4px;
	}

	.shortcut-overlay {
		position: fixed;
		inset: 0;
		background: rgba(0, 0, 0, 0.5);
		display: flex;
		align-items: center;
		justify-content: center;
	}

	.shortcut-panel {
		background: white;
		padding: 2rem;
		border-radius: 12px;
		max-width: 400px;
	}

	.shortcut-panel ul {
		list-style: none;
		padding: 0;
	}

	.shortcut-panel li {
		display: flex;
		justify-content: space-between;
		padding: 0.5rem 0;
		border-bottom: 1px solid #eee;
	}
</style>

Este exemplo demonstra vários padrões importantes. Primeiro, observe como o estado do teclado é gerenciado de forma reativa usando $state. O Set activeKeys rastreia quais teclas estão sendo pressionadas no momento, atualizado tanto nos eventos keydown quanto keyup. Isso permite a detecção de combinações de teclas, não apenas pressionamentos individuais.

A função shouldIgnoreEvent implementa um padrão crítico de UX: desabilitar atalhos quando o usuário está interagindo com elementos de formulário. Sem essa guarda, os usuários não poderiam digitar a letra 's' em um campo de input sem acionar uma ação de salvar. A exceção para a tecla Escape reflete expectativas comuns — os usuários tipicamente esperam que o Escape funcione em qualquer lugar.

A normalização de teclas trata das diferenças entre plataformas. No macOS, a tecla Command é reportada como 'Meta', mas muitas aplicações tratam Command no Mac de forma equivalente ao Control no Windows/Linux. A normalização permite que uma única definição de atalho funcione em todas as plataformas.

O Padrão de Clique Fora: Um Caso de Uso Clássico

Uma das razões mais comuns para recorrer ao <svelte:body> é implementar o comportamento de "clicar fora para fechar". Esse padrão aparece em menus suspensos, diálogos modais, descarte de tooltips e inúmeras outras interações de UI.

A implementação ingênua tem um bug sutil, mas significativo:

<!-- AVOID: Don't do this -->
<script>
	let isOpen = $state(false)
</script>

<svelte:body onclick={() => (isOpen = false)} />

<div class="dropdown">
	<button onclick={() => (isOpen = !isOpen)}>Toggle Menu</button>
	{#if isOpen}
		<div class="menu">
			<a href="/profile">Profile</a>
			<a href="/settings">Settings</a>
			<a href="/logout">Logout</a>
		</div>
	{/if}
</div>

O bug: clicar no botão de alternância dispara tanto o manipulador de clique do botão (que tenta abrir o menu) quanto o manipulador de clique do body (que o fecha). Devido ao borbulhamento de eventos, clicar em qualquer lugar dentro do componente também aciona o manipulador do body.

Aqui está a implementação corrigida com tratamento adequado de eventos:

<script>
	let isOpen = $state(false)
	let dropdownElement = $state(null)

	function handleBodyClick(event) {
		// Only close if click originated outside the dropdown
		if (dropdownElement && !dropdownElement.contains(event.target)) {
			isOpen = false
		}
	}

	function toggleDropdown(event) {
		// Stop propagation to prevent immediate close
		event.stopPropagation()
		isOpen = !isOpen
	}

	function handleMenuClick(event) {
		// Optional: close menu after selecting an option
		// Remove this if you want the menu to stay open
		isOpen = false
	}
</script>

<svelte:body onclick={handleBodyClick} />

<div class="dropdown" bind:this={dropdownElement}>
	<button onclick={toggleDropdown} aria-expanded={isOpen}>
		Toggle Menu
		<span class="arrow">{isOpen ? '▲' : '▼'}</span>
	</button>

	{#if isOpen}
		<nav class="menu" role="menu">
			<a href="/profile" role="menuitem" onclick={handleMenuClick}>Profile</a>
			<a href="/settings" role="menuitem" onclick={handleMenuClick}>Settings</a>
			<a href="/logout" role="menuitem" onclick={handleMenuClick}>Logout</a>
		</nav>
	{/if}
</div>

<style>
	.dropdown {
		position: relative;
		display: inline-block;
	}

	.menu {
		position: absolute;
		top: 100%;
		left: 0;
		background: white;
		border: 1px solid #ddd;
		border-radius: 4px;
		box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
		min-width: 150px;
		z-index: 100;
	}

	.menu a {
		display: block;
		padding: 0.75rem 1rem;
		color: inherit;
		text-decoration: none;
	}

	.menu a:hover {
		background: #f5f5f5;
	}
</style>

A percepção fundamental é usar element.contains(event.target) para determinar se o clique ocorreu dentro ou fora do dropdown. Essa abordagem é mais robusta do que interromper a propagação em todo lugar, o que pode interferir com outras manipulações de eventos na sua aplicação.

Uma Implementação de Clique Fora Mais Sofisticada

Para aplicações em produção, considere uma action reutilizável ou um sistema de detecção mais sofisticado:

<script>
	let isOpen = $state(false)
	let menuEl = $state(null)
	let buttonEl = $state(null)

	// Track the last interaction source to handle edge cases
	let lastInteractionSource = $state(null)

	function handleBodyClick(event) {
		// Ignore if the dropdown isn't open
		if (!isOpen) return

		// Check if click was inside the menu or button
		const clickedInside = menuEl?.contains(event.target) || buttonEl?.contains(event.target)

		if (!clickedInside) {
			isOpen = false
			lastInteractionSource = 'outside-click'
		}
	}

	function handleBodyKeydown(event) {
		if (!isOpen) return

		switch (event.key) {
			case 'Escape':
				isOpen = false
				lastInteractionSource = 'escape-key'
				// Return focus to the trigger button
				buttonEl?.focus()
				break

			case 'Tab':
				// Close dropdown when tabbing away
				// Slight delay to allow focus to move first
				requestAnimationFrame(() => {
					const focusInDropdown =
						menuEl?.contains(document.activeElement) || buttonEl?.contains(document.activeElement)

					if (!focusInDropdown) {
						isOpen = false
						lastInteractionSource = 'tab-away'
					}
				})
				break
		}
	}

	function toggleDropdown() {
		isOpen = !isOpen
		lastInteractionSource = isOpen ? 'button-click' : 'button-toggle'

		// Focus first menu item when opening
		if (isOpen) {
			requestAnimationFrame(() => {
				menuEl?.querySelector('a')?.focus()
			})
		}
	}
</script>

<svelte:body onclick={handleBodyClick} onkeydown={handleBodyKeydown} />

<div class="dropdown-container">
	<button bind:this={buttonEl} onclick={toggleDropdown} aria-expanded={isOpen} aria-haspopup="menu">
		Options
	</button>

	{#if isOpen}
		<nav bind:this={menuEl} class="dropdown-menu" role="menu" aria-label="Options menu">
			<a href="/edit" role="menuitem">Edit</a>
			<a href="/duplicate" role="menuitem">Duplicate</a>
			<a href="/archive" role="menuitem">Archive</a>
			<hr />
			<a href="/delete" role="menuitem" class="danger">Delete</a>
		</nav>
	{/if}
</div>

Esta implementação trata a navegação por teclado adequadamente, retorna o foco ao gatilho ao fechar via Escape e rastreia a origem das interações para fins de depuração ou análise.

Modificadores de Eventos e Fase de Captura

Em versões anteriores do Svelte, você podia aplicar modificadores como capture, once e passive usando a sintaxe de pipe: on:click|capture|once. No Svelte 5, a abordagem difere — você trabalha com as opções do manipulador de eventos de forma mais direta.

Para manipulação de eventos na fase de captura (onde você intercepta eventos durante a fase de captura em vez da fase de borbulhamento), você pode usar o padrão de atributo onclickcapture:

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

	function addToLog(message) {
		log = [...log, { time: Date.now(), message }]
	}

	// Capture phase - fires first, before any target handlers
	function handleCaptureClick(event) {
		addToLog(`Capture phase: ${event.target.tagName}`)
	}

	// Bubble phase - fires after target handlers, during bubbling
	function handleBubbleClick(event) {
		addToLog(`Bubble phase: ${event.target.tagName}`)
	}
</script>

<!-- Capture phase handler - note the 'capture' suffix -->
<svelte:body onclickcapture={handleCaptureClick} onclick={handleBubbleClick} />

<div class="demo">
	<button onclick={() => addToLog('Button clicked directly')}>
		Click me to see event phases
	</button>

	<div class="log">
		{#each log as entry}
			<div class="log-entry">{entry.message}</div>
		{/each}
	</div>

	<button onclick={() => (log = [])}>Clear Log</button>
</div>

A manipulação na fase de captura é particularmente útil quando você precisa interceptar eventos antes que eles alcancem seus destinos pretendidos. Um caso de uso comum é implementar um prompt global de "tem certeza que deseja sair?":

<script>
	let hasUnsavedChanges = $state(false)

	function interceptNavigation(event) {
		// Only intercept anchor clicks
		const anchor = event.target.closest('a')
		if (!anchor) return

		// Only intercept internal navigation
		if (anchor.hostname !== window.location.hostname) return

		if (hasUnsavedChanges) {
			event.preventDefault()
			event.stopPropagation()

			const confirmed = window.confirm('You have unsaved changes. Are you sure you want to leave?')

			if (confirmed) {
				hasUnsavedChanges = false
				// Programmatically navigate after confirmation
				window.location.href = anchor.href
			}
		}
	}
</script>

<svelte:body onclickcapture={interceptNavigation} />

Integrando com a Reatividade do Svelte 5: A Conexão com `$effect`

O verdadeiro poder do <svelte:body> emerge quando combinado com o sistema de reatividade do Svelte 5. Você pode criar manipuladores de eventos que respondem ao estado reativo, usar $effect para gerenciar efeitos colaterais acionados por eventos no body e construir padrões de interação sofisticados.

Considere este exemplo de um recurso de "modo de apresentação" que responde tanto a entradas do teclado quanto a estado externo:

<script>
	// Core presentation state
	let slides = $state([
		{ id: 1, title: 'Introduction', content: 'Welcome to the presentation' },
		{ id: 2, title: 'Main Points', content: 'Here are the key ideas' },
		{ id: 3, title: 'Deep Dive', content: 'Let us explore further' },
		{ id: 4, title: 'Conclusion', content: 'Thank you for attending' }
	])

	let currentSlideIndex = $state(0)
	let isPresentationMode = $state(false)
	let isPointerVisible = $state(true)
	let pointerHideTimeout = $state(null)

	// Derived values
	let currentSlide = $derived(slides[currentSlideIndex])
	let progress = $derived(((currentSlideIndex + 1) / slides.length) * 100)
	let canGoBack = $derived(currentSlideIndex > 0)
	let canGoForward = $derived(currentSlideIndex < slides.length - 1)

	// Navigation functions
	function nextSlide() {
		if (canGoForward) {
			currentSlideIndex++
		}
	}

	function previousSlide() {
		if (canGoBack) {
			currentSlideIndex--
		}
	}

	function goToSlide(index) {
		if (index >= 0 && index < slides.length) {
			currentSlideIndex = index
		}
	}

	// Keyboard navigation for presentation mode
	function handlePresentationKeydown(event) {
		if (!isPresentationMode) return

		switch (event.key) {
			case 'ArrowRight':
			case 'ArrowDown':
			case ' ':
			case 'PageDown':
				event.preventDefault()
				nextSlide()
				break

			case 'ArrowLeft':
			case 'ArrowUp':
			case 'PageUp':
				event.preventDefault()
				previousSlide()
				break

			case 'Home':
				event.preventDefault()
				goToSlide(0)
				break

			case 'End':
				event.preventDefault()
				goToSlide(slides.length - 1)
				break

			case 'Escape':
				event.preventDefault()
				isPresentationMode = false
				break

			case 'f':
			case 'F':
				event.preventDefault()
				toggleFullscreen()
				break
		}
	}

	// Hide pointer after inactivity
	function handleMouseMove() {
		if (!isPresentationMode) return

		isPointerVisible = true

		// Clear existing timeout
		if (pointerHideTimeout) {
			clearTimeout(pointerHideTimeout)
		}

		// Set new timeout to hide pointer
		pointerHideTimeout = setTimeout(() => {
			isPointerVisible = false
		}, 3000)
	}

	function toggleFullscreen() {
		if (!document.fullscreenElement) {
			document.documentElement.requestFullscreen()
		} else {
			document.exitFullscreen()
		}
	}

	// Effect to manage body class for presentation mode styling
	$effect(() => {
		if (isPresentationMode) {
			document.body.classList.add('presentation-active')
		} else {
			document.body.classList.remove('presentation-active')
		}

		// Cleanup when effect re-runs or component unmounts
		return () => {
			document.body.classList.remove('presentation-active')
		}
	})

	// Effect to announce slide changes for screen readers
	$effect(() => {
		if (isPresentationMode && currentSlide) {
			// Create an aria-live announcement
			const announcement = document.createElement('div')
			announcement.setAttribute('aria-live', 'polite')
			announcement.setAttribute('aria-atomic', 'true')
			announcement.className = 'sr-only'
			announcement.textContent = `Slide ${currentSlideIndex + 1} of ${slides.length}: ${currentSlide.title}`

			document.body.appendChild(announcement)

			// Remove after announcement is made
			setTimeout(() => {
				announcement.remove()
			}, 1000)
		}
	})
</script>

<svelte:body onkeydown={handlePresentationKeydown} onmousemove={handleMouseMove} />

{#if !isPresentationMode}
	<div class="editor-view">
		<header>
			<h1>Presentation Editor</h1>
			<button onclick={() => (isPresentationMode = true)}> Start Presentation </button>
		</header>

		<div class="slide-list">
			{#each slides as slide, index}
				<div
					class={['slide-thumbnail', index === currentSlideIndex && 'active']}
					onclick={() => (currentSlideIndex = index)}
				>
					<span class="slide-number">{index + 1}</span>
					<span class="slide-title">{slide.title}</span>
				</div>
			{/each}
		</div>

		<div class="slide-editor">
			<h2>{currentSlide.title}</h2>
			<p>{currentSlide.content}</p>
		</div>
	</div>
{:else}
	<div class={['presentation-view', !isPointerVisible && 'pointer-hidden']}>
		<div class="slide">
			<h1>{currentSlide.title}</h1>
			<p>{currentSlide.content}</p>
		</div>

		<div class="presentation-controls">
			<div class="progress-bar">
				<div class="progress-fill" style="width: {progress}%"></div>
			</div>

			<div class="slide-counter">
				{currentSlideIndex + 1} / {slides.length}
			</div>
		</div>

		<nav class="presentation-nav" aria-label="Slide navigation">
			<button onclick={previousSlide} disabled={!canGoBack} aria-label="Previous slide"> ← </button>
			<button onclick={nextSlide} disabled={!canGoForward} aria-label="Next slide"> → </button>
		</nav>
	</div>
{/if}

<style>
	.presentation-view {
		position: fixed;
		inset: 0;
		background: #1a1a2e;
		color: white;
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
	}

	.presentation-view.pointer-hidden {
		cursor: none;
	}

	.slide {
		text-align: center;
		padding: 2rem;
	}

	.slide h1 {
		font-size: 3rem;
		margin-bottom: 1rem;
	}

	.progress-bar {
		position: fixed;
		bottom: 0;
		left: 0;
		right: 0;
		height: 4px;
		background: rgba(255, 255, 255, 0.2);
	}

	.progress-fill {
		height: 100%;
		background: #4ade80;
		transition: width 0.3s ease;
	}

	.presentation-nav {
		position: fixed;
		bottom: 2rem;
		display: flex;
		gap: 1rem;
	}

	.sr-only {
		position: absolute;
		width: 1px;
		height: 1px;
		padding: 0;
		margin: -1px;
		overflow: hidden;
		clip: rect(0, 0, 0, 0);
		border: 0;
	}
</style>

Este exemplo demonstra vários padrões avançados. Os blocos $effect gerenciam efeitos colaterais que se estendem além do template do componente — adicionando uma classe ao body do documento e criando anúncios de acessibilidade. O manipulador de movimento do mouse cria um comportamento de "ocultar cursor quando inativo", comum em softwares de apresentação. E o manipulador de teclado demonstra como a manipulação de eventos do <svelte:body> pode ser condicionalmente ativa com base no estado da aplicação.

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

Ao construir aplicações que usam renderização no lado do servidor (SSR), você deve considerar como o <svelte:body> se comporta durante a fase de renderização no servidor. Como não há um DOM real no servidor, o <svelte:body> efetivamente se torna um no-op durante o SSR — nenhum ouvinte de evento é anexado.

Esse geralmente é o comportamento desejado. No entanto, você precisa ter cuidado com qualquer lógica nos seus manipuladores de eventos que presuma um ambiente de navegador:

<script>
	import { browser } from '$app/environment' // SvelteKit-specific

	function handleKeydown(event) {
		// This check isn't strictly necessary for <svelte:body> handlers
		// (they only fire in the browser), but it's good practice
		// for any shared utilities that might be called from handlers
		if (!browser) return

		// Safe to use browser APIs here
		const isInputFocused = document.activeElement?.tagName === 'INPUT'

		if (!isInputFocused && event.key === '/') {
			event.preventDefault()
			document.querySelector('#search-input')?.focus()
		}
	}
</script>

<svelte:body onkeydown={handleKeydown} />

De forma mais sutil, se o seu componente inicializa estado com base em APIs do navegador durante a criação do componente, esse código será executado no servidor onde essas APIs não existem:

<script>
	// AVOID:This will error during SSR
	// let windowWidth = $state(window.innerWidth);

	// PREFERRED: Safe - initialize with a default, update in effect
	let windowWidth = $state(0)

	$effect(() => {
		// This only runs in the browser
		windowWidth = window.innerWidth

		function handleResize() {
			windowWidth = window.innerWidth
		}

		window.addEventListener('resize', handleResize)

		return () => {
			window.removeEventListener('resize', handleResize)
		}
	})
</script>

<svelte:body onkeydown={handleKeydown} />

<div>Window width: {windowWidth || 'Loading...'}</div>

Note que para eventos de redimensionamento de janela especificamente, você tipicamente usaria <svelte:window> em vez de <svelte:body>, mas a consideração sobre SSR se aplica a qualquer inicialização que dependa do navegador.

Considerações de Performance e Boas Práticas

Embora o <svelte:body> forneça uma abstração limpa, é importante entender as implicações de performance da manipulação de eventos no nível do body.

Eventos de Alta Frequência

Eventos como mousemove, scroll (no body) e pointermove podem disparar dezenas de vezes por segundo. Anexar handlers para esses eventos requer consideração cuidadosa:

<script>
	let mousePosition = $state({ x: 0, y: 0 })

	// AVOID: Potentially problematic: updates state on every mouse move
	function handleMouseMove(event) {
		mousePosition = { x: event.clientX, y: event.clientY }
	}

	// PREFERRED: throttle updates
	let lastUpdate = 0
	const THROTTLE_MS = 16 // ~60fps

	function handleMouseMoveThrottled(event) {
		const now = Date.now()
		if (now - lastUpdate < THROTTLE_MS) return

		lastUpdate = now
		mousePosition = { x: event.clientX, y: event.clientY }
	}

	// PREFERRED Alternative: use requestAnimationFrame for visual updates
	let rafId = null
	let pendingPosition = null

	function handleMouseMoveRAF(event) {
		pendingPosition = { x: event.clientX, y: event.clientY }

		if (rafId === null) {
			rafId = requestAnimationFrame(() => {
				mousePosition = pendingPosition
				rafId = null
			})
		}
	}
</script>

<svelte:body onmousemove={handleMouseMoveRAF} />

Anexação Condicional de Handlers

Em alguns casos, você pode querer evitar anexar handlers de eventos quando eles não são necessários. Infelizmente, <svelte:body> não suporta renderização condicional da forma que elementos regulares fazem — ele está sempre presente. No entanto, você pode fazer com que os handlers sejam essencialmente no-ops:

<script>
	let featureEnabled = $state(false)

	// Handler returns early when feature is disabled
	function handleKeydown(event) {
		if (!featureEnabled) return

		// Actual handling logic
		if (event.key === 'Enter') {
			performAction()
		}
	}
</script>

<svelte:body onkeydown={handleKeydown} />

Para tratamento de eventos verdadeiramente opcional, quando você deseja evitar completamente o overhead do listener, pode ser necessário recorrer à abordagem imperativa com $effect:

<script>
	let featureEnabled = $state(false)

	$effect(() => {
		if (!featureEnabled) return

		function handleKeydown(event) {
			if (event.key === 'Enter') {
				performAction()
			}
		}

		document.body.addEventListener('keydown', handleKeydown)

		return () => {
			document.body.removeEventListener('keydown', handleKeydown)
		}
	})
</script>

Múltiplos Componentes com Handlers no Body

Quando múltiplos componentes em sua aplicação usam <svelte:body>, todos os seus handlers serão acionados para cada evento. Isso geralmente não é um problema, mas pode levar a comportamentos inesperados se não for considerado:

<!-- ComponentA.svelte -->
<script>
  function handleClick(event) {
    console.log('Component A saw click');
    // This doesn't prevent ComponentB from also seeing the click
  }
</script>

<svelte:body onclick={handleClick} />

<!-- ComponentB.svelte -->
<script>
  function handleClick(event) {
    console.log('Component B saw click');
  }
</script>

<svelte:body onclick={handleClick} />

Se você precisar coordenar múltiplos handlers no nível do body, considere usar um sistema centralizado de gerenciamento de eventos:

<!-- eventBus.svelte.js -->
<script module>
	let handlers = $state(new Map())
	let handlerPriorities = $state(new Map())

	export function registerHandler(id, handler, priority = 0) {
		handlers.set(id, handler)
		handlerPriorities.set(id, priority)
	}

	export function unregisterHandler(id) {
		handlers.delete(id)
		handlerPriorities.delete(id)
	}

	export function dispatch(event) {
		// Sort handlers by priority (higher priority = runs first)
		const sortedHandlers = [...handlers.entries()].sort(
			(a, b) => handlerPriorities.get(b[0]) - handlerPriorities.get(a[0])
		)

		for (const [id, handler] of sortedHandlers) {
			const result = handler(event)

			// Allow handlers to stop propagation to other handlers
			if (result === false) break
		}
	}
</script>

Armadilhas Comuns e Como Evitá-las

Vamos catalogar os erros mais comuns que desenvolvedores cometem com <svelte:body> e estabelecer padrões claros para evitá-los.

1. Esquecer a Limpeza de Eventos ao Usar Padrões Imperativos

Se você precisar complementar <svelte:body> com tratamento imperativo de eventos, sempre garanta a limpeza:

<script>
	$effect(() => {
		// Some imperative setup that complements <svelte:body>
		const handler = () => {
			/* ... */
		}
		document.body.addEventListener('custom-event', handler)

		// CRITICAL: Return cleanup function
		return () => {
			document.body.removeEventListener('custom-event', handler)
		}
	})
</script>

2. Bloquear Comportamento Padrão do Navegador Inesperadamente

Tenha cuidado com event.preventDefault() em handlers no nível do body. Você pode acidentalmente quebrar o comportamento esperado do navegador:

<script>
	function handleKeydown(event) {
		// AVOID:This prevents ALL keyboard shortcuts, including browser ones
		// event.preventDefault();

		// PREFERRED: only prevent default for specific keys you're handling
		if (event.key === 's' && (event.ctrlKey || event.metaKey)) {
			event.preventDefault()
			saveDocument()
		}
	}
</script>

<svelte:body onkeydown={handleKeydown} />

3. Não Considerar o Estado de Foco

Handlers de teclado especialmente precisam considerar qual elemento está atualmente em foco:

<script>
	function handleKeydown(event) {
		// AVOID: This fires even when user is typing in a form
		// if (event.key === 'Delete') { deleteSelectedItem(); }

		// PREFERRED: Check if we're in an editable context
		const activeElement = document.activeElement
		const isEditing = activeElement?.matches('input, textarea, select, [contenteditable="true"]')

		if (!isEditing && event.key === 'Delete') {
			deleteSelectedItem()
		}
	}
</script>

<svelte:body onkeydown={handleKeydown} />

4. Suposições sobre a Ordem de Execução de Handlers

Não assuma uma ordem específica de execução entre handlers de <svelte:body> em componentes diferentes. Se a ordem importar, use mecanismos explícitos de coordenação:

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

	// Create a context for coordinating keyboard handlers
	const KEYBOARD_CONTEXT = Symbol('keyboard')

	// In a parent component
	setContext(KEYBOARD_CONTEXT, {
		layers: [],
		register(handler, priority) {
			this.layers.push({ handler, priority })
			this.layers.sort((a, b) => b.priority - a.priority)
		},
		unregister(handler) {
			this.layers = this.layers.filter((l) => l.handler !== handler)
		},
		dispatch(event) {
			for (const layer of this.layers) {
				if (layer.handler(event) === false) return
			}
		}
	})
</script>

5. Vazamentos de Memória com Closures

Handlers de eventos que fecham sobre estado reativo podem inadvertidamente criar vazamentos de memória ou problemas de closure obsoleto:

<script>
	let items = $state(['a', 'b', 'c'])

	// AVOID: This handler closes over `items` at definition time
	// In Svelte 5, this actually works correctly due to how $state
	// creates reactive references, but be aware of the pattern
	function handleKeydown(event) {
		console.log('Items:', items) // This will see current items
	}
</script>

<svelte:body onkeydown={handleKeydown} />

No Svelte 5 com runes, isso geralmente é tratado corretamente porque $state cria referências reativas em vez de valores estáticos. No entanto, se você estiver trabalhando com estado aninhado complexo ou valores não reativos, esteja atento à semântica de closures.

Comparação com Padrões Relacionados

Vale a pena entender quando usar <svelte:body> versus abordagens alternativas.

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

<svelte:window> anexa handlers ao objeto window, enquanto <svelte:body> anexa ao document.body. As diferenças práticas:

Eventos resize e scroll (no nível da janela) devem usar <svelte:window>
A maioria dos eventos de teclado e mouse pode usar qualquer um, mas <svelte:body> é semanticamente mais apropriado para eventos que conceitualmente acontecem "dentro da página"
beforeunload e hashchange devem usar <svelte:window>

<svelte:window onresize={handleResize} onbeforeunload={handleBeforeUnload} />

<svelte:body onkeydown={handleKeydown} onclick={handleClick} />

Usando Actions com `<svelte:body>`

O elemento <svelte:body> suporta a diretiva use:, permitindo que você anexe actions do Svelte diretamente ao elemento body. Isso é útil para comportamentos que precisam ser aplicados ao corpo inteiro do documento:

<script>
	function trackClicks(node) {
		function handleClick(event) {
			console.log('Body clicked at:', event.clientX, event.clientY)
		}

		node.addEventListener('click', handleClick)

		return {
			destroy() {
				node.removeEventListener('click', handleClick)
			}
		}
	}
</script>

<svelte:body use:trackClicks />

Este padrão é particularmente útil ao integrar bibliotecas de terceiros que precisam anexar comportamento ao elemento body, ou quando você tem comportamentos reutilizáveis no nível do body em múltiplos componentes.

`<svelte:body>` vs `<svelte:document>`

O Svelte também fornece <svelte:document> para anexar handlers ao objeto document. Use isso para eventos no nível do documento, como visibilitychange:

<script>
	let isVisible = $state(true)

	function handleVisibilityChange() {
		isVisible = !document.hidden
	}
</script>

<svelte:document onvisibilitychange={handleVisibilityChange} />

{#if !isVisible}
	<!-- Pause videos, animations, etc. when tab is hidden -->
{/if}

`<svelte:body>` vs Attachments

Para comportamento reutilizável no nível de elemento, o Svelte 5.29+ fornece attachments através da diretiva {@attach}. Attachments são a substituição moderna para actions (use:), oferecendo melhor reatividade e composabilidade. No entanto, para eventos verdadeiramente globais, <svelte:body> continua sendo a escolha certa:

<script>
	// Attachment: reusable, element-specific behavior (Svelte 5.29+)
	function clickOutside(callback) {
		return (node) => {
			function handleClick(event) {
				if (!node.contains(event.target)) {
					callback()
				}
			}

			document.body.addEventListener('click', handleClick, true)

			// Cleanup function runs when element is removed
			return () => {
				document.body.removeEventListener('click', handleClick, true)
			}
		}
	}
</script>

<!-- Use attachments for element-specific click-outside -->
<div {@attach clickOutside(() => (isOpen = false))}>
	<!-- Dropdown content -->
</div>

<!-- Use <svelte:body> for global keyboard shortcuts -->
<svelte:body onkeydown={handleGlobalKeydown} />

Attachments têm diversas vantagens sobre a sintaxe antiga de action use::

Totalmente reativos: São re-executados automaticamente quando as dependências mudam
Combináveis: Podem ser espalhados em componentes e passados através de props
Suporte inline: Podem ser definidos inline sem declarações de funções separadas
Melhor suporte a TypeScript: Suporte completo a genéricos e inferência de tipos aprimorada

Juntando Tudo: Um Exemplo Completo

Vamos concluir com um exemplo abrangente que demonstra múltiplos padrões de <svelte:body> funcionando em harmonia — uma aplicação de desenho com atalhos de teclado, alternância de ferramentas e comportamento de clique externo:

<script>
	// Application state
	let currentTool = $state('brush')
	let brushSize = $state(10)
	let brushColor = $state('#000000')
	let isDrawing = $state(false)
	let showColorPicker = $state(false)
	let showHelp = $state(false)

	let canvasRef = $state(null)
	let colorPickerRef = $state(null)
	let lastPosition = $state(null)

	// Tool definitions
	const tools = [
		{ id: 'brush', key: 'b', name: 'Brush', icon: '🖌️' },
		{ id: 'eraser', key: 'e', name: 'Eraser', icon: '🧹' },
		{ id: 'fill', key: 'f', name: 'Fill', icon: '🪣' },
		{ id: 'picker', key: 'i', name: 'Color Picker', icon: '💉' }
	]

	// Keyboard shortcuts handler
	function handleKeydown(event) {
		// Don't intercept when typing in inputs
		if (event.target.matches('input, textarea')) return

		// Help overlay toggle
		if (event.key === '?' || (event.key === '/' && event.shiftKey)) {
			event.preventDefault()
			showHelp = !showHelp
			return
		}

		// Close any open panels with Escape
		if (event.key === 'Escape') {
			if (showHelp) showHelp = false
			if (showColorPicker) showColorPicker = false
			return
		}

		// Don't process other shortcuts if help is showing
		if (showHelp) return

		// Tool switching with single keys
		const tool = tools.find((t) => t.key === event.key.toLowerCase())
		if (tool) {
			currentTool = tool.id
			return
		}

		// Brush size adjustment
		if (event.key === '[') {
			brushSize = Math.max(1, brushSize - 5)
			return
		}
		if (event.key === ']') {
			brushSize = Math.min(100, brushSize + 5)
			return
		}

		// Color picker toggle
		if (event.key === 'c') {
			showColorPicker = !showColorPicker
			return
		}

		// Undo/Redo
		if ((event.ctrlKey || event.metaKey) && event.key === 'z') {
			event.preventDefault()
			if (event.shiftKey) {
				redo()
			} else {
				undo()
			}
			return
		}
	}

	// Click outside handler for color picker
	function handleClick(event) {
		if (showColorPicker && colorPickerRef && !colorPickerRef.contains(event.target)) {
			// Check if click was on the toggle button
			if (!event.target.closest('[data-color-toggle]')) {
				showColorPicker = false
			}
		}
	}

	// Canvas interaction handlers via body (for drag that might leave canvas)
	function handleMouseMove(event) {
		if (!isDrawing || !canvasRef) return

		const rect = canvasRef.getBoundingClientRect()
		const x = event.clientX - rect.left
		const y = event.clientY - rect.top

		if (x >= 0 && x <= rect.width && y >= 0 && y <= rect.height) {
			draw(x, y)
		}

		lastPosition = { x: event.clientX, y: event.clientY }
	}

	function handleMouseUp() {
		if (isDrawing) {
			isDrawing = false
			lastPosition = null
			saveToHistory()
		}
	}

	// Canvas-specific mouse down (not on body)
	function handleCanvasMouseDown(event) {
		isDrawing = true
		const rect = canvasRef.getBoundingClientRect()
		lastPosition = {
			x: event.clientX - rect.left,
			y: event.clientY - rect.top
		}
	}

	// Drawing implementation
	function draw(x, y) {
		if (!canvasRef || !lastPosition) return

		const ctx = canvasRef.getContext('2d')

		ctx.beginPath()
		ctx.moveTo(lastPosition.x, lastPosition.y)
		ctx.lineTo(x, y)
		ctx.strokeStyle = currentTool === 'eraser' ? '#ffffff' : brushColor
		ctx.lineWidth = brushSize
		ctx.lineCap = 'round'
		ctx.lineJoin = 'round'
		ctx.stroke()

		lastPosition = { x, y }
	}

	// History management (simplified)
	let history = $state([])
	let historyIndex = $state(-1)

	function saveToHistory() {
		// Save canvas state to history
		if (!canvasRef) return
		const imageData = canvasRef.toDataURL()
		history = [...history.slice(0, historyIndex + 1), imageData]
		historyIndex = history.length - 1
	}

	function undo() {
		if (historyIndex > 0) {
			historyIndex--
			restoreFromHistory()
		}
	}

	function redo() {
		if (historyIndex < history.length - 1) {
			historyIndex++
			restoreFromHistory()
		}
	}

	function restoreFromHistory() {
		if (!canvasRef || !history[historyIndex]) return

		const img = new Image()
		img.onload = () => {
			const ctx = canvasRef.getContext('2d')
			ctx.clearRect(0, 0, canvasRef.width, canvasRef.height)
			ctx.drawImage(img, 0, 0)
		}
		img.src = history[historyIndex]
	}

	// Initialize canvas
	$effect(() => {
		if (canvasRef) {
			const ctx = canvasRef.getContext('2d')
			ctx.fillStyle = '#ffffff'
			ctx.fillRect(0, 0, canvasRef.width, canvasRef.height)
			saveToHistory()
		}
	})
</script>

<!-- Body-level event handlers -->
<svelte:body
	onkeydown={handleKeydown}
	onclick={handleClick}
	onmousemove={handleMouseMove}
	onmouseup={handleMouseUp}
/>

<div class="drawing-app">
	<header class="toolbar">
		<div class="tool-group">
			{#each tools as tool}
				<button
					class="tool-button"
					class:active={currentTool === tool.id}
					onclick={() => (currentTool = tool.id)}
					title="{tool.name} ({tool.key})"
				>
					{tool.icon}
				</button>
			{/each}
		</div>

		<div class="tool-group">
			<label class="size-control">
				Size: {brushSize}px
				<input type="range" min="1" max="100" bind:value={brushSize} />
			</label>
		</div>

		<div class="tool-group">
			<button
				class="color-button"
				data-color-toggle
				onclick={() => (showColorPicker = !showColorPicker)}
				style="background-color: {brushColor}"
				title="Color (c)"
			>
				<span class="sr-only">Select color</span>
			</button>

			{#if showColorPicker}
				<div class="color-picker-popup" bind:this={colorPickerRef}>
					<input type="color" bind:value={brushColor} />
					<div class="color-presets">
						{#each ['#000000', '#ff0000', '#00ff00', '#0000ff', '#ffff00', '#ff00ff'] as color}
							<button
								class="preset"
								style="background-color: {color}"
								onclick={() => {
									brushColor = color
									showColorPicker = false
								}}
							></button>
						{/each}
					</div>
				</div>
			{/if}
		</div>

		<div class="tool-group">
			<button onclick={() => (showHelp = true)} title="Help (?)"> ❓ </button>
		</div>
	</header>

	<main class="canvas-container">
		<canvas bind:this={canvasRef} width="800" height="600" onmousedown={handleCanvasMouseDown}
		></canvas>

		<div class="status-bar">
			Tool: {tools.find((t) => t.id === currentTool)?.name} | Size: {brushSize}px | Color: {brushColor}
		</div>
	</main>

	{#if showHelp}
		<div class="help-overlay" role="dialog" aria-label="Keyboard shortcuts">
			<div class="help-panel">
				<h2>Keyboard Shortcuts</h2>

				<section>
					<h3>Tools</h3>
					<ul>
						{#each tools as tool}
							<li><kbd>{tool.key}</kbd> {tool.name}</li>
						{/each}
					</ul>
				</section>

				<section>
					<h3>Brush Size</h3>
					<ul>
						<li><kbd>[</kbd> Decrease size</li>
						<li><kbd>]</kbd> Increase size</li>
					</ul>
				</section>

				<section>
					<h3>Other</h3>
					<ul>
						<li><kbd>c</kbd> Toggle color picker</li>
						<li><kbd>Ctrl+Z</kbd> Undo</li>
						<li><kbd>Ctrl+Shift+Z</kbd> Redo</li>
						<li><kbd>?</kbd> Toggle this help</li>
						<li><kbd>Esc</kbd> Close panels</li>
					</ul>
				</section>

				<button onclick={() => (showHelp = false)}>Close</button>
			</div>
		</div>
	{/if}
</div>

<style>
	.drawing-app {
		display: flex;
		flex-direction: column;
		height: 100vh;
		font-family: system-ui, sans-serif;
	}

	.toolbar {
		display: flex;
		gap: 1rem;
		padding: 0.5rem 1rem;
		background: #f5f5f5;
		border-bottom: 1px solid #ddd;
		align-items: center;
	}

	.tool-group {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		position: relative;
	}

	.tool-button {
		width: 40px;
		height: 40px;
		font-size: 1.25rem;
		border: 2px solid transparent;
		background: white;
		border-radius: 4px;
		cursor: pointer;
	}

	.tool-button.active {
		border-color: #007bff;
		background: #e7f1ff;
	}

	.color-button {
		width: 40px;
		height: 40px;
		border: 2px solid #ccc;
		border-radius: 4px;
		cursor: pointer;
	}

	.color-picker-popup {
		position: absolute;
		top: 100%;
		left: 0;
		background: white;
		padding: 1rem;
		border-radius: 8px;
		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
		z-index: 100;
	}

	.color-presets {
		display: flex;
		gap: 0.5rem;
		margin-top: 0.5rem;
	}

	.preset {
		width: 24px;
		height: 24px;
		border: 1px solid #ccc;
		border-radius: 4px;
		cursor: pointer;
	}

	.canvas-container {
		flex: 1;
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
		padding: 1rem;
		background: #e0e0e0;
	}

	canvas {
		border: 1px solid #ccc;
		background: white;
		cursor: crosshair;
	}

	.status-bar {
		margin-top: 0.5rem;
		font-size: 0.875rem;
		color: #666;
	}

	.help-overlay {
		position: fixed;
		inset: 0;
		background: rgba(0, 0, 0, 0.5);
		display: flex;
		align-items: center;
		justify-content: center;
		z-index: 1000;
	}

	.help-panel {
		background: white;
		padding: 2rem;
		border-radius: 12px;
		max-width: 500px;
		max-height: 80vh;
		overflow-y: auto;
	}

	.help-panel h2 {
		margin-top: 0;
	}

	.help-panel section {
		margin: 1rem 0;
	}

	.help-panel ul {
		list-style: none;
		padding: 0;
	}

	.help-panel li {
		padding: 0.25rem 0;
	}

	kbd {
		background: #eee;
		border: 1px solid #ccc;
		border-radius: 3px;
		padding: 0.1em 0.4em;
		font-family: monospace;
		font-size: 0.9em;
	}

	.sr-only {
		position: absolute;
		width: 1px;
		height: 1px;
		padding: 0;
		margin: -1px;
		overflow: hidden;
		clip: rect(0, 0, 0, 0);
		border: 0;
	}
</style>

Conclusão

<svelte:body> representa uma das soluções mais elegantes do Svelte para um desafio comum do desenvolvimento web — gerenciar interações no nível global sem comprometer a arquitetura declarativa e baseada em componentes que torna os frameworks modernos valiosos. De atalhos de teclado a padrões de clique externo, de arrastar e soltar a modos de apresentação, a capacidade de anexar declarativamente event listeners ao body do documento abre padrões de interação sofisticados que de outra forma exigiriam tedioso boilerplate imperativo.

Os padrões e exemplos neste tutorial demonstram que dominar <svelte:body> não é apenas aprender sintaxe — é entender propagação de eventos, considerar acessibilidade, gerenciar desempenho e arquitetar soluções reutilizáveis. À medida que você constrói aplicações mais complexas, as técnicas discutidas aqui — lógica condicional de handlers, gerenciamento coordenado de estado, inicialização com consciência de SSR — se mostrarão inestimáveis.

Principais Conclusões

<svelte:body> fornece tratamento de eventos declarativo e seguro para SSR no nível do body do documento com limpeza automática de listeners, eliminando riscos de vazamento de memória e gerenciamento imperativo do ciclo de vida
Handlers de eventos usam a sintaxe de atributo on* no Svelte 5 (onkeydown, onclick, onmousemove) com tratamento opcional da fase de captura via sufixo capture (onclickcapture)
A detecção de clique externo requer verificações com element.contains(event.target) para evitar disparos em cliques dentro do componente, combinado com event.stopPropagation() nos botões de alternância
Sistemas de atalhos de teclado precisam de filtragem de entrada usando shouldIgnoreEvent() para evitar interferência com campos de formulário, ainda permitindo teclas de escape, e normalização de teclas entre plataformas para teclas modificadoras
Eventos de alta frequência (mousemove, scroll) requerem throttling via requestAnimationFrame ou throttling baseado em tempo para evitar degradação de desempenho causada por dezenas de atualizações de estado por segundo
Múltiplos componentes com handlers no body executam todos os handlers para cada evento, exigindo mecanismos centralizados de coordenação ou sistemas de prioridade quando a ordem de execução importar
A diretiva {@attach} (Svelte 5.29+) oferece uma alternativa para comportamento específico de elemento com melhor reatividade do que actions use:, embora <svelte:body> permaneça ideal para eventos verdadeiramente globais
O comportamento SSR torna <svelte:body> um no-op no servidor sem event listeners anexados, embora handlers que referenciam APIs do navegador ainda devam verificar o contexto do navegador em utilitários compartilhados

Veja Também

Documentação Oficial do Svelte 5 - <svelte:body>
MDN Web Docs - Bubbling e Captura de Eventos
<svelte:window> - Tratamento de eventos no nível da janela para resize, scroll e outros eventos específicos da janela
<svelte:document> - Eventos no nível do documento como mudanças de visibilidade e tela cheia
Tratamento de Eventos de Teclado - Entendendo propriedades de eventos de teclado e diferenças entre plataformas
Melhores Práticas ARIA - Padrões de acessibilidade para navegação por teclado e gerenciamento de foco
Svelte 5 Runes - $effect - Efeitos colaterais que complementam o tratamento de eventos no nível do body
API de Performance - requestAnimationFrame - Throttling eficiente de eventos de alta frequência