Svelte參考

編譯器警告

Svelte 會在編譯時警告您潛在的錯誤，例如撰寫無法存取的標記。

某些警告在您的實際使用案例中可能不正確。您可以透過在導致警告的行上方放置  註解來停用此類誤報。範例

<!-- svelte-ignore a11y_autofocus -->
<input autofocus />

您可以在單一註解中列出多個規則（以逗號分隔），並在旁邊加上說明（以括號表示）

<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions (because of reasons) -->
<div onclick>...</div>

a11y_accesskey

Avoid using accesskey

強制元素上不使用 accesskey。存取鍵是 HTML 屬性，可讓網頁開發人員將鍵盤快捷鍵指派給元素。鍵盤快捷鍵與螢幕閱讀器和僅使用鍵盤的使用者所使用的鍵盤命令之間的不一致會造成可存取性問題。為了避免複雜情況，不應使用存取鍵。

<!-- A11y: Avoid using accesskey -->
<div accesskey="z"></div>

a11y_aria_activedescendant_has_tabindex

An element with an aria-activedescendant attribute should have a tabindex value

具有 aria-activedescendant 的元素必須是可使用 Tab 鍵瀏覽的，因此它必須具有內建的 tabindex 或將 tabindex 宣告為屬性。

<!-- A11y: Elements with attribute aria-activedescendant should have tabindex value -->
<div aria-activedescendant="some-id"></div>

a11y_aria_attributes

`<%name%>` should not have aria-* attributes

某些保留的 DOM 元素不支援 ARIA 角色、狀態和屬性。這通常是因為它們不可見，例如 meta、html、script、style。此規則強制這些 DOM 元素不包含 aria-* 屬性。

<!-- A11y: <meta> should not have aria-* attributes -->
<meta aria-hidden="false" />

a11y_autocomplete_valid

'%value%' is an invalid value for 'autocomplete' on `<input type="%type%">`

a11y_autofocus

Avoid using autofocus

強制元素上不使用 autofocus。自動對焦元素可能會對有視力和無視力的使用者造成可用性問題。

<!-- A11y: Avoid using autofocus -->
<input autofocus />

a11y_click_events_have_key_events

Visible, non-interactive elements with a click event must be accompanied by a keyboard event handler. Consider whether an interactive element such as `<button type="button">` or `<a>` might be more appropriate. See https://svelte.dev.org.tw/docs/accessibility-warnings#a11y-click-events-have-key-events for more details

強制具有 onclick 事件的 visible 非互動式元素需搭配鍵盤事件處理常式。

使用者應首先考慮使用互動式元素是否更合適，例如用於動作的 <button type="button"> 元素或用於導覽的 <a> 元素。這些元素語意更豐富，並且具有內建的按鍵處理。例如，Space 和 Enter 將會觸發 <button>，而 Enter 將會觸發 <a> 元素。

如果需要非互動式元素，則 onclick 應搭配 onkeyup 或 onkeydown 處理常式，讓使用者可以透過鍵盤執行等效的操作。為了讓使用者能夠觸發按鍵，該元素還需要透過新增 tabindex 來聚焦。雖然 onkeypress 處理常式也會使此警告靜音，但應注意 keypress 事件已棄用。

<!-- A11y: visible, non-interactive elements with an onclick event must be accompanied by a keyboard event handler. -->
<div onclick={() => {}}></div>

為鍵盤編寫程式碼對於無法使用滑鼠、AT 相容性和螢幕閱讀器使用者的身心障礙使用者非常重要。

a11y_consider_explicit_label

Buttons and links should either contain text or have an `aria-label` or `aria-labelledby` attribute

a11y_distracting_elements

Avoid `<%name%>` elements

強制不使用分散注意力的元素。可能會分散視覺注意力的元素可能會對視力受損的使用者造成可存取性問題。此類元素很可能已棄用，應避免使用。

以下元素會分散視覺注意力：<marquee> 和 <blink>。

<!-- A11y: Avoid <marquee> elements -->
<marquee></marquee>

a11y_figcaption_index

`<figcaption>` must be first or last child of `<figure>`

a11y_figcaption_parent

`<figcaption>` must be an immediate child of `<figure>`

強制某些 DOM 元素具有正確的結構。

<!-- A11y: <figcaption> must be an immediate child of <figure> -->
<div>
	<figcaption>Image caption</figcaption>
</div>

a11y_hidden

`<%name%>` element should not be hidden

某些 DOM 元素對於螢幕閱讀器導覽非常有用，不應隱藏。

<!-- A11y: <h2> element should not be hidden -->
<h2 aria-hidden="true">invisible header</h2>

a11y_img_redundant_alt

Screenreaders already announce `<img>` elements as an image

強制 img alt 屬性不包含單字 image、picture 或 photo。螢幕閱讀器已將 img 元素宣告為影像。無需使用例如image、photo 和/或 picture 等詞。

<img src="foo" alt="Foo eating a sandwich." />

<!-- aria-hidden, won't be announced by screen reader -->
<img src="bar" aria-hidden="true" alt="Picture of me taking a photo of an image" />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="foo" alt="Photo of foo being weird." />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="bar" alt="Image of me at a bar!" />

<!-- A11y: Screen readers already announce <img> elements as an image. -->
<img src="foo" alt="Picture of baz fixing a bug." />

a11y_incorrect_aria_attribute_type

The value of '%attribute%' must be a %type%

強制僅將正確類型的值用於 aria 屬性。例如，aria-hidden 應僅接收布林值。

<!-- A11y: The value of 'aria-hidden' must be exactly one of true or false -->
<div aria-hidden="yes"></div>

a11y_incorrect_aria_attribute_type_boolean

The value of '%attribute%' must be either 'true' or 'false'. It cannot be empty

a11y_incorrect_aria_attribute_type_id

The value of '%attribute%' must be a string that represents a DOM element ID

a11y_incorrect_aria_attribute_type_idlist

The value of '%attribute%' must be a space-separated list of strings that represent DOM element IDs

a11y_incorrect_aria_attribute_type_integer

The value of '%attribute%' must be an integer

a11y_incorrect_aria_attribute_type_token

The value of '%attribute%' must be exactly one of %values%

a11y_incorrect_aria_attribute_type_tokenlist

The value of '%attribute%' must be a space-separated list of one or more of %values%

a11y_incorrect_aria_attribute_type_tristate

The value of '%attribute%' must be exactly one of true, false, or mixed

a11y_interactive_supports_focus

Elements with the '%role%' interactive role must have a tabindex value

強制具有互動角色和互動處理常式（滑鼠或按鍵）的元素必須是可聚焦或可使用 Tab 鍵瀏覽的。

<!-- A11y: Elements with the 'button' interactive role must have a tabindex value. -->
<div role="button" onkeypress={() => {}} />

a11y_invalid_attribute

'%href_value%' is not a valid %href_attribute% attribute

強制對於可存取性很重要的屬性具有有效值。例如，href 不應為空、'#' 或 javascript:。

<!-- A11y: '' is not a valid href attribute -->
<a href="">invalid</a>

a11y_label_has_associated_control

A form label must be associated with a control

強制標籤標籤具有文字標籤和關聯的控制項。

有兩種支援的方式可以將標籤與控制項關聯

將控制項包裝在標籤標籤中。
在標籤中新增 for 並將其指派給頁面上輸入的 ID。

<label for="id">B</label>

<label>C <input type="text" /></label>

<!-- A11y: A form label must be associated with a control. -->
<label>A</label>

a11y_media_has_caption

`<video>` elements must have a `<track kind="captions">`

為媒體提供字幕對於聽障使用者來說非常重要。字幕應為對話、音效、相關音樂提示和其他相關音訊資訊的轉錄或翻譯。這不僅對可存取性很重要，而且在媒體無法使用時，對於所有使用者也可能有用（類似於影像無法載入時的影像上的 alt 文字）。

字幕應包含理解相應媒體的所有重要和相關資訊。這可能表示字幕不是媒體內容中對話的 1:1 對應。但是，對於具有 muted 屬性的視訊元件，則不需要字幕。

<video><track kind="captions" /></video>

<audio muted></audio>

<!-- A11y: Media elements must have a <track kind=\"captions\"> -->
<video></video>

<!-- A11y: Media elements must have a <track kind=\"captions\"> -->
<video><track /></video>

a11y_misplaced_role

`<%name%>` should not have role attribute

某些保留的 DOM 元素不支援 ARIA 角色、狀態和屬性。這通常是因為它們不可見，例如 meta、html、script、style。此規則強制這些 DOM 元素不包含 role 屬性。

<!-- A11y: <meta> should not have role attribute -->
<meta role="tooltip" />

a11y_misplaced_scope

The scope attribute should only be used with `<th>` elements

scope 屬性應僅在 <th> 元素上使用。

<!-- A11y: The scope attribute should only be used with <th> elements -->
<div scope="row" />

a11y_missing_attribute

`<%name%>` element should have %article% %sequence% attribute

強制在元素上存在可存取性所需的屬性。這包括以下檢查

<a> 應具有 href（除非它是定義片段的標籤）
<area> 應具有 alt、aria-label 或 aria-labelledby
<html> 應具有 lang
<iframe> 應具有 title
<img> 應具有 alt
<object> 應具有 title、aria-label 或 aria-labelledby
<input type="image"> 應具有 alt、aria-label 或 aria-labelledby

<!-- A11y: <input type=\"image\"> element should have an alt, aria-label or aria-labelledby attribute -->
<input type="image" />

<!-- A11y: <html> element should have a lang attribute -->
<html></html>

<!-- A11y: <a> element should have an href attribute -->
<a>text</a>

a11y_missing_content

`<%name%>` element should contain text

強制標題元素（h1、h2 等）和錨點具有內容，並且螢幕閱讀器可以存取該內容

<!-- A11y: <a> element should have child content -->
<a href="/foo"></a>

<!-- A11y: <h1> element should have child content -->
<h1></h1>

a11y_mouse_events_have_key_events

'%event%' event must be accompanied by '%accompanied_by%' event

強制 onmouseover 和 onmouseout 事件必須分別搭配 onfocus 和 onblur 事件。這有助於確保由這些滑鼠事件觸發的任何功能，鍵盤使用者也能夠存取。

<!-- A11y: onmouseover must be accompanied by onfocus -->
<div onmouseover={handleMouseover} />

<!-- A11y: onmouseout must be accompanied by onblur -->
<div onmouseout={handleMouseout} />

a11y_no_abstract_role

Abstract role '%role%' is forbidden

a11y_no_interactive_element_to_noninteractive_role

`<%element%>` cannot have role '%role%'

WAI-ARIA 角色不應被用來將互動式元素轉換為非互動式元素。非互動式 ARIA 角色包含 article、banner、complementary、img、listitem、main、region 和 tooltip。

<!-- A11y: <textarea> cannot have role 'listitem' -->
<textarea role="listitem"></textarea>

a11y_no_noninteractive_element_interactions

Non-interactive element `<%element%>` should not be assigned mouse or keyboard event listeners

非互動式元素不支援事件處理器（滑鼠和鍵盤處理器）。非互動式元素包含 <main>、<area>、<h1> (、<h2> 等)、<p>、<img>、<li>、<ul> 和 <ol>。非互動式 WAI-ARIA 角色包含 article、banner、complementary、img、listitem、main、region 和 tooltip。

<!-- `A11y: Non-interactive element <li> should not be assigned mouse or keyboard event listeners.` -->
<li onclick={() => {}}></li>

<!-- `A11y: Non-interactive element <div> should not be assigned mouse or keyboard event listeners.` -->
<div role="listitem" onclick={() => {}}></div>

a11y_no_noninteractive_element_to_interactive_role

Non-interactive element `<%element%>` cannot have interactive role '%role%'

WAI-ARIA 角色不應被用來將非互動式元素轉換為互動式元素。互動式 ARIA 角色包含 button、link、checkbox、menuitem、menuitemcheckbox、menuitemradio、option、radio、searchbox、switch 和 textbox。

<!-- A11y: Non-interactive element <h3> cannot have interactive role 'searchbox' -->
<h3 role="searchbox">Button</h3>

a11y_no_noninteractive_tabindex

noninteractive element cannot have nonnegative tabIndex value

Tab 鍵導覽應僅限於頁面上可與之互動的元素。

<!-- A11y: noninteractive element cannot have nonnegative tabIndex value -->
<div tabindex="0"></div>

a11y_no_redundant_roles

Redundant role '%role%'

某些 HTML 元素具有預設的 ARIA 角色。為這些元素賦予瀏覽器已設定的 ARIA 角色沒有任何作用，而且是多餘的。

<!-- A11y: Redundant role 'button' -->
<button role="button">...</button>

<!-- A11y: Redundant role 'img' -->
<img role="img" src="foo.jpg" />

a11y_no_static_element_interactions

`<%element%>` with a %handler% handler must have an ARIA role

具有互動式處理器（如 click）的 <div> 等元素必須具有 ARIA 角色。

<!-- A11y: <div> with click handler must have an ARIA role -->
<div onclick={() => ''}></div>

a11y_positive_tabindex

Avoid tabindex values above zero

避免使用正值的 tabindex 屬性值。這會將元素移出預期的 tab 順序，為鍵盤使用者造成混淆的體驗。

<!-- A11y: avoid tabindex values above zero -->
<div tabindex="1"></div>

a11y_role_has_required_aria_props

Elements with the ARIA role "%role%" must have the following attributes defined: %props%

具有 ARIA 角色的元素必須具有該角色所需的所有屬性。

<!-- A11y: A11y: Elements with the ARIA role "checkbox" must have the following attributes defined: "aria-checked" -->
<span role="checkbox" aria-labelledby="foo" tabindex="0"></span>

a11y_role_supports_aria_props

The attribute '%attribute%' is not supported by the role '%role%'

具有明確或隱含定義的角色的元素，僅包含該角色支援的 aria-* 屬性。

<!-- A11y: The attribute 'aria-multiline' is not supported by the role 'link'. -->
<div role="link" aria-multiline></div>

<!-- A11y: The attribute 'aria-required' is not supported by the role 'listitem'. This role is implicit on the element <li>. -->
<li aria-required></li>

a11y_role_supports_aria_props_implicit

The attribute '%attribute%' is not supported by the role '%role%'. This role is implicit on the element `<%name%>`

具有明確或隱含定義的角色的元素，僅包含該角色支援的 aria-* 屬性。

<!-- A11y: The attribute 'aria-multiline' is not supported by the role 'link'. -->
<div role="link" aria-multiline></div>

<!-- A11y: The attribute 'aria-required' is not supported by the role 'listitem'. This role is implicit on the element <li>. -->
<li aria-required></li>

a11y_unknown_aria_attribute

Unknown aria attribute 'aria-%attribute%'

Unknown aria attribute 'aria-%attribute%'. Did you mean '%suggestion%'?

強制僅使用已知的 ARIA 屬性。這是基於 WAI-ARIA 狀態和屬性規格。

<!-- A11y: Unknown aria attribute 'aria-labeledby' (did you mean 'labelledby'?) -->
<input type="image" aria-labeledby="foo" />

a11y_unknown_role

Unknown role '%role%'

Unknown role '%role%'. Did you mean '%suggestion%'?

具有 ARIA 角色的元素必須使用有效的、非抽象的 ARIA 角色。角色定義的參考文檔可在 WAI-ARIA 網站找到。

<!-- A11y: Unknown role 'toooltip' (did you mean 'tooltip'?) -->
<div role="toooltip"></div>

attribute_avoid_is

The "is" attribute is not supported cross-browser and should be avoided

attribute_global_event_reference

You are referencing `globalThis.%name%`. Did you forget to declare a variable with that name?

attribute_illegal_colon

Attributes should not contain ':' characters to prevent ambiguity with Svelte directives

attribute_invalid_property_name

'%wrong%' is not a valid HTML attribute. Did you mean '%right%'?

attribute_quoted

Quoted attributes on components and custom elements will be stringified in a future version of Svelte. If this isn't what you want, remove the quotes

bind_invalid_each_rest

The rest operator (...) will create a new object and binding '%name%' with the original object will not work

block_empty

Empty block

component_name_lowercase

`<%name%>` will be treated as an HTML element unless it begins with a capital letter

css_unused_selector

Unused CSS selector "%name%"

element_invalid_self_closing_tag

Self-closing HTML tags for non-void elements are ambiguous — use `<%name% ...></%name%>` rather than `<%name% ... />`

event_directive_deprecated

Using `on:%name%` to listen to the %name% event is deprecated. Use the event attribute `on%name%` instead

export_let_unused

Component has unused export property '%name%'. If it is for external reference only, please consider using `export const %name%`

legacy_code

`%code%` is no longer valid — please use `%suggestion%` instead

legacy_component_creation

Svelte 5 components are no longer classes. Instantiate them using `mount` or `hydrate` (imported from 'svelte') instead.

node_invalid_placement_ssr

%message%. When rendering this component on the server, the resulting HTML will be modified by the browser (by moving, removing, or inserting elements), likely resulting in a `hydration_mismatch` warning

HTML 限制了某些元素可以出現的位置。如果發生違規，瀏覽器會以一種會破壞 Svelte 對元件結構的假設的方式「修復」HTML。一些範例：

<p>hello <div>world</div></p> 將導致 <p>hello </p><div>world</div><p></p> （<div> 自動關閉了 <p>，因為 <p> 不能包含區塊級元素）
<option><div>option a</div></option> 將導致 <option>option a</option> (<div> 被移除)
<table><tr><td>cell</td></tr></table> 將導致 <table><tbody><tr><td>cell</td></tr></tbody></table> (自動插入 <tbody>)

當元件在客戶端渲染時，此程式碼可以正常運作（這就是為什麼這是一個警告而不是錯誤），但是如果您使用伺服器渲染，它將導致水合作用失敗。

non_reactive_update

`%name%` is updated, but is not declared with `$state(...)`. Changing its value will not correctly trigger updates

options_deprecated_accessors

The `accessors` option has been deprecated. It will have no effect in runes mode

options_deprecated_immutable

The `immutable` option has been deprecated. It will have no effect in runes mode

options_missing_custom_element

The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?

options_removed_enable_sourcemap

The `enableSourcemap` option has been removed. Source maps are always generated now, and tooling can choose to ignore them

options_removed_hydratable

The `hydratable` option has been removed. Svelte components are always hydratable now

options_removed_loop_guard_timeout

The `loopGuardTimeout` option has been removed

options_renamed_ssr_dom

`generate: "dom"` and `generate: "ssr"` options have been renamed to "client" and "server" respectively

perf_avoid_inline_class

Avoid 'new class' — instead, declare the class at the top level scope

perf_avoid_nested_class

Avoid declaring classes below the top level scope

reactive_declaration_invalid_placement

Reactive declarations only exist at the top level of the instance script

reactive_declaration_module_script_dependency

Reassignments of module-level declarations will not cause reactive statements to update

script_context_deprecated

`context="module"` is deprecated, use the `module` attribute instead

script_unknown_attribute

Unrecognized attribute — should be one of `generics`, `lang` or `module`. If this exists for a preprocessor, ensure that the preprocessor removes it

slot_element_deprecated

Using `<slot>` to render parent content is deprecated. Use `{@render ...}` tags instead

state_referenced_locally

State referenced in its own scope will never update. Did you mean to reference it inside a closure?

store_rune_conflict

It looks like you're using the `$%name%` rune, but there is a local binding called `%name%`. Referencing a local variable with a `$` prefix will create a store subscription. Please rename `%name%` to avoid the ambiguity

svelte_component_deprecated

`<svelte:component>` is deprecated in runes mode — components are dynamic by default

在舊版 Svelte 中，元件建構子在元件渲染時是固定的。換句話說，如果您希望在 X 變更時重新渲染 <X>，您必須使用 <svelte:component this={X}> 或將元件放在 {#key X}...{/key} 區塊內。

在 Svelte 5 中，情況不再如此 — 如果 X 變更，則 <X> 會重新渲染。

在某些情況下，可以使用 <object.property> 語法作為替代；在 Svelte 5 中，具有屬性存取的小寫變數會被識別為元件。

對於複雜的元件解析邏輯，可能需要一個中間的、大寫的變數。例如，在可以使用 @const 的地方

{#each items as item}
	<svelte:component this={item.condition ? Y : Z} />
	{@const Component = item.condition ? Y : Z}
	<Component />
{/each}

導出的值可以用於其他上下文中

<script>
	// ...
	let condition = $state(false);
	const Component = $derived(condition ? Y : Z);
</script>

<svelte:component this={condition ? Y : Z} />
<Component />

svelte_element_invalid_this

`this` should be an `{expression}`. Using a string attribute value will cause an error in future versions of Svelte

svelte_self_deprecated

`<svelte:self>` is deprecated — use self-imports (e.g. `import %name% from './%basename%'`) instead

unknown_code

`%code%` is not a recognised code

`%code%` is not a recognised code (did you mean `%suggestion%`?)

在 GitHub 上編輯此頁面

編譯器錯誤執行階段錯誤