Svelte 最新中文文档翻译（5）—— 基础标记

[mqyqingfeng]

前言

Svelte，一个非常“有趣”、用起来“很爽”的前端框架。从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级、高性能、易上手等特性，非常适合构建轻量级 Web 项目，也是我做个人项目的首选技术栈。

目前 Svelte 基于 Svelte 5 发布了最新的官方文档，但却缺少对应的中文文档。为了帮助大家学习 Svelte，为爱发电翻译了官方文档。

我同时搭建了 Svelte 最新的中文文档站点：https://svelte.yayujs.com ，如果需要辅助学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

虽说是翻译，但个人并不喜欢严格遵守原文，为了保证中文阅读流畅，会删减部分语句，对难懂的部分也会另做补充解释，希望能给大家带来一个好的中文学习体验。

欢迎围观我的“朋友圈”、加入“低调务实优秀中国好青年”前端社群，分享技术，带你成长。

基础标记

Svelte 组件内的标记可以被理解为增强版的 HTML。

标签

小写标签，如 <div>，表示常规的 HTML 元素。大写标签或使用点符号的标签，如 <Widget> 或 <my.stuff>，表示一个组件。

<script>
	import Widget from './Widget.svelte';
</script>

<div>
	<Widget />
</div>

元素属性

默认情况下，属性的工作方式与其 HTML 对应项完全相同。

<div class="foo">
	<button disabled>can't touch this</button>
</div>

与 HTML 一样，属性值可以不加引号。

<input type=checkbox />

属性值可以包含 JavaScript 表达式。

<a href="page/{p}">page {p}</a>

或者它们本身就可以是 JavaScript 表达式。

<button disabled={!clickable}>...</button>

如果布尔属性的值为真值，则会包含在元素中，如果为假值，则会被排除。

所有其他属性除非其值为空值（null 或 undefined），否则都会被包含。

<input required={false} placeholder="This input field is not required" />
<div title={null}>This div has no title attribute</div>

[!NOTE] 在单个表达式外加引号不会影响值的解析方式，但在 Svelte 6 中会导致值被强制转换为字符串：

<button disabled="{number !== 42}">...</button>

当属性名和值相同时（name={name}），可以简写为 {name}。

<button {disabled}>...</button>
<!-- 等同于
<button disabled={disabled}>...</button>
-->

组件属性

按照惯例，传递给组件的值被称为属性（properties）或props，而不是特性（attributes），后者是 DOM 的一个特征。

译者注：Property 和 Attributes 通常都翻译为“属性”，在做区分时，通常会将 Attributes 翻译为“特性”。Attributes 指的是直接在 HTML 元素上设置的值，通过提供元素的附加信息来指导其初始行为和状态。

与元素一样，name={name} 可以简写为 {name}。

<Widget foo={bar} answer={42} text="hello" />

展开属性允许一次性将多个特性或属性传递给元素或组件。

一个元素或组件可以有多个展开属性，并与常规属性交错使用。

<Widget {...things} />

事件

通过在元素上添加以 on 开头的属性，可以监听 DOM 事件。例如，要监听 click 事件，在按钮上添加 onclick 属性：

<button onclick={() => console.log('clicked')}>click me</button>

事件属性区分大小写。onclick 监听 click 事件，onClick 监听 Click 事件，这是不同的。这确保你可以监听包含大写字符的自定义事件。

因为事件只是属性，所以适用与属性相同的规则：

• 你可以使用简写形式：<button {onclick}>click me</button>
• 你可以展开它们：<button {...thisSpreadContainsEventAttributes}>click me</button>

在时序上，事件属性总是在绑定事件之后触发（例如，oninput 总是在 bind:value 更新后触发）。在底层，一些事件处理程序是直接通过 addEventListener 附加的，而其他的则是委托的。

当使用 ontouchstart 和 ontouchmove 事件属性时，处理程序是passive可以获得更好的性能。这极大地提高了响应性，因为浏览器可以立即滚动文档，而不是等待查看事件处理程序是否调用 event.preventDefault()。

在极少数情况下，如果你需要阻止这些事件的默认行为，你应该使用 on（例如在 action 内部）。

事件委托

为了减少内存占用并提高性能，Svelte 使用了一种称为事件委托的技术。这意味着对于某些事件（见下面的列表），在应用程序根部的单个事件监听器负责运行事件路径上的所有处理程序。

需要注意以下几个陷阱：

• 当你手动触发一个带有委托监听器的事件时，确保设置 { bubbles: true } 选项，否则它将无法到达应用程序根部
• 当直接使用 addEventListener 时，避免调用 stopPropagation，否则事件将无法到达应用程序根部，处理程序将不会被调用。同样，在应用程序根部手动添加的处理程序将在 DOM 深处声明式添加的处理程序（例如用 onclick={...}）之前运行，无论是在捕获还是冒泡阶段。出于这些原因，最好使用从 svelte/events 导入的 on 函数，而不是 addEventListener，因为它将确保顺序得到保持，并且正确处理 stopPropagation。

以下事件处理程序是委托的：

• beforeinput
• click
• change
• dblclick
• contextmenu
• focusin
• focusout
• input
• keydown
• keyup
• mousedown
• mousemove
• mouseout
• mouseover
• mouseup
• pointerdown
• pointermove
• pointerout
• pointerover
• pointerup
• touchend
• touchmove
• touchstart

文本表达式

可以通过将 JavaScript 表达式用大括号括起来将其作为文本包含。

{expression}

可以通过使用它们的 HTML 实体字符串在 Svelte 模板中包含大括号：{、{ 或 { 表示 {，}、} 或 } 表示 }。

如果你使用正则表达式（RegExp）字面量表示法，你需要用括号将其括起来。

<h1>Hello {name}!</h1>
<p>{a} + {b} = {a + b}.</p>

<div>{(/^[A-Za-z ]+$/).test(value) ? x : y}</div>

表达式将被字符串化并转义以防止代码注入。如果你想渲染 HTML，请使用 {@html} 标签。

{@html potentiallyUnsafeHtmlString}

[!NOTE] 确保你要么对传入的字符串进行转义，要么只使用你控制下的值来填充它，以防止 XSS 攻击

注释

你可以在组件内使用 HTML 注释。

<!-- this is a comment! --><h1>Hello world</h1>

以 svelte-ignore 开头的注释会禁用下一个标记块的警告。通常，这些是可访问性警告；确保你有充分的理由禁用它们。

<!-- svelte-ignore a11y-autofocus -->
<input bind:value={name} autofocus />

你可以添加一个以 @component 开头的特殊注释，当在其他文件中悬停在组件名称上时会显示该注释。

<!--
@component
- You can use markdown here.
- You can also use code blocks here.
- Usage:
  ```html
  <Main name="Arethra">
  ```
-->
<script>
	let { name } = $props();
</script>

<main>
	<h1>
		Hello, {name}
	</h1>
</main>

Svelte 中文文档

本篇已收录在掘金专栏 《Svelte 中文文档》，该系列预计 40 篇。

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog

通过文字建立交流本身就是一种缘分，欢迎围观我的“朋友圈”、加入“低调务实优秀中国好青年”前端社群，分享技术，带你成长。