Skip to main content
Svelte参考文档

svelte/compiler

import { const VERSION: string
The current version, as set in package.json.


https://svelte.dev/docs/svelte-compiler#svelte-version


VERSION, function compile(source: string, options: CompileOptions): CompileResult
compile converts your .svelte source code into a JavaScript module that exports a component


@paramsource The component source code
@paramoptions The compiler options
compile, function compileModule(source: string, options: ModuleCompileOptions): CompileResult
compileModule takes your JavaScript source code containing runes, and turns it into a JavaScript module.


@paramsource The component source code
compileModule, 
function migrate(source: string, { filename, use_ts }?: {
    filename?: string;
    use_ts?: boolean;
} | undefined): {
    code: string;
}
Does a best-effort migration of Svelte code towards using runes, event attributes and render tags.
May throw an error if the code is too complex to migrate automatically.


migrate, 
function parse(source: string, options: {
    filename?: string;
    modern: true;
    loose?: boolean;
}): AST.Root (+1 overload)
The parse function parses a component, returning only its abstract syntax tree.


The modern option (false by default in Svelte 5) makes the parser return a modern AST instead of the legacy AST.
modern will become true by default in Svelte 6, and the option will be removed in Svelte 7.


parse, 
function preprocess(source: string, preprocessor: PreprocessorGroup | PreprocessorGroup[], options?: {
    filename?: string;
} | undefined): Promise<Processed>
The preprocess function provides convenient hooks for arbitrarily transforming component source code.
For example, it can be used to convert a &#x3C;style lang="sass"> block into vanilla CSS.


preprocess, function walk(): never
@deprecatedReplace this with import { walk } from 'estree-walker'
walk } from 'svelte/compiler';

版本

当前版本，在 package.json 中设置。

/docs/svelte-compiler#svelte-version

const VERSION: string;

compile

compile 将您的 .svelte 源代码转换为一个导出组件的 JavaScript 模块。

function compile(
	source: string,
	options: CompileOptions
): CompileResult;

compileModule

compileModule 将包含符文的 JavaScript 源代码转换为 JavaScript 模块。

function compileModule(
	source: string,
	options: ModuleCompileOptions
): CompileResult;

migrate

尽力将 Svelte 代码迁移到使用符文、事件属性和渲染标签。 如果代码过于复杂，可能会抛出错误，无法自动迁移。

function migrate(
	source: string,
	{
		filename,
		use_ts
	}?:
		| {
				filename?: string;
				use_ts?: boolean;
		  }
		| undefined
): {
	code: string;
};

parse

解析函数解析一个组件，只返回其抽象语法树。

modern 选项（在 Svelte 5 中默认设置为 false）使解析器返回现代 AST，而不是遗留 AST。

在 Svelte 6 中，modern 将默认设置为 true，并将在 Svelte 7 中删除该选项。

function parse(
	source: string,
	options: {
		filename?: string;
		modern: true;
		loose?: boolean;
	}
): AST.Root;
function parse(
	source: string,
	options?:
		| {
				filename?: string;
				modern?: false;
				loose?: boolean;
		  }
		| undefined
): Record<string, any>;

preprocess

preprocess 函数提供方便的钩子，用于任意转换组件源代码。 例如，它可以用于将 <style lang="sass"> 块转换为普通 CSS。

function preprocess(
	source: string,
	preprocessor: PreprocessorGroup | PreprocessorGroup[],
	options?:
		| {
				filename?: string;
		  }
		| undefined
): Promise<Processed>;

walk

用 import { walk } from 'estree-walker' 替换此内容

function walk(): never;

AST

namespace AST {
	export interface BaseNode {
		type: string;
		start: number;
		end: number;
	}

	export interface Fragment {
		type: 'Fragment';
		nodes: Array<
			Text | Tag | ElementLike | Block | Comment
		>;
	}

	export interface Root extends BaseNode {
		type: 'Root';
		/**
		 * 由 `<svelte:options>` 提供的行内选项——这些选项覆盖传递给 `compile(...)` 的选项
		 */
		options: SvelteOptions | null;
		fragment: Fragment;
		/** 解析的 `<style>` 元素（如果存在） */
		css: AST.CSS.StyleSheet | null;
		/** 解析的 `<script>` 元素（如果存在） */
		instance: Script | null;
		/** 解析的 `<script module>` 元素（如果存在） */
		module: Script | null;
	}

	export interface SvelteOptions {
		// 开始/结束信息（用于警告及我们的 Prettier 插件）
		start: number;
		end: number;
		// 选项
		runes?: boolean;
		immutable?: boolean;
		accessors?: boolean;
		preserveWhitespace?: boolean;
		namespace?: Namespace;
		css?: 'injected';
		customElement?: {
			tag?: string;
			shadow?: 'open' | 'none';
			props?: Record<
				string,
				{
					attribute?: string;
					reflect?: boolean;
					type?:
						| 'Array'
						| 'Boolean'
						| 'Number'
						| 'Object'
						| 'String';
				}
			>;
			/**
			 * 类型为
			 * ```ts
			 * (ceClass: new () => HTMLElement) => new () => HTMLElement
			 * ```
			 */
			extend?: ArrowFunctionExpression | Identifier;
		};
		attributes: Attribute[];
	}

	/** 静态文本 */
	export interface Text extends BaseNode {
		type: 'Text';
		/** 解析后的文本，其中包含解码的 HTML 实体 */
		data: string;
		/** 原始文本，包含未解码的 HTML 实体 */
		raw: string;
	}

	/** 一个（可能是反应式的）模板表达式 — `{...}` */
	export interface ExpressionTag extends BaseNode {
		type: 'ExpressionTag';
		expression: Expression;
	}

	/** 一个（可能是反应式的）HTML模板表达式 — `{@html ...}` */
	export interface HtmlTag extends BaseNode {
		type: 'HtmlTag';
		expression: Expression;
	}

	/** HTML 注释 */
	// TODO 重命名以消歧
	export interface Comment extends BaseNode {
		type: 'Comment';
		/** 注释的内容 */
		data: string;
	}

	/** 一个 `{@const ...}` 标签 */
	export interface ConstTag extends BaseNode {
		type: 'ConstTag';
		declaration: VariableDeclaration & {
			declarations: [
				VariableDeclarator & {
					id: Pattern;
					init: Expression;
				}
			];
		};
	}

	/** 一个 `{@debug ...}` 标签 */
	export interface DebugTag extends BaseNode {
		type: 'DebugTag';
		identifiers: Identifier[];
	}

	/** 一个 `{@render foo(...)}` 标签 */
	export interface RenderTag extends BaseNode {
		type: 'RenderTag';
		expression:
			| SimpleCallExpression
			| (ChainExpression & {
					expression: SimpleCallExpression;
			  });
	}

	/** 一个 `animate:` 指令 */
	export interface AnimateDirective extends BaseNode {
		type: 'AnimateDirective';
		/** `animate:x` 中的 'x' */
		name: string;
		/** `animate:x={y}` 中的 y */
		expression: null | Expression;
	}

	/** 一个 `bind:` 指令 */
	export interface BindDirective extends BaseNode {
		type: 'BindDirective';
		/** `bind:x` 中的 'x' */
		name: string;
		/** `bind:x={y}` 中的 y */
		expression:
			| Identifier
			| MemberExpression
			| SequenceExpression;
	}

	/** 一个 `class:` 指令 */
	export interface ClassDirective extends BaseNode {
		type: 'ClassDirective';
		/** `class:x` 中的 'x' */
		name: 'class';
		/** `class:x={y}` 中的 y，或 `class:x` 中的 `x` */
		expression: Expression;
	}

	/** 一个 `let:` 指令 */
	export interface LetDirective extends BaseNode {
		type: 'LetDirective';
		/** `let:x` 中的 'x' */
		name: string;
		/** `let:x={y}` 中的 y */
		expression:
			| null
			| Identifier
			| ArrayExpression
			| ObjectExpression;
	}

	/** 一个 `on:` 指令 */
	export interface OnDirective extends BaseNode {
		type: 'OnDirective';
		/** `on:x` 中的 'x' */
		name: string;
		/** `on:x={y}` 中的 y */
		expression: null | Expression;
		modifiers: string[];
	}

	/** 一个 `style:` 指令 */
	export interface StyleDirective extends BaseNode {
		type: 'StyleDirective';
		/** `style:x` 中的 'x' */
		name: string;
		/** `style:x={y}` 中的 y */
		value:
			| true
			| ExpressionTag
			| Array<ExpressionTag | Text>;
		modifiers: Array<'important'>;
	}

	// TODO 拥有单独的 in/out/transition 指令
	/** 一个 `transition:`, `in:` 或 `out:` 指令 */
	export interface TransitionDirective extends BaseNode {
		type: 'TransitionDirective';
		/** `transition:x` 中的 'x' */
		name: string;
		/** `transition:x={y}` 中的 y */
		expression: null | Expression;
		modifiers: Array<'local' | 'global'>;
		/** 如果这是一个 `transition:` 或 `in:` 指令为真 */
		intro: boolean;
		/** 如果这是一个 `transition:` 或 `out:` 指令为真 */
		outro: boolean;
	}

	/** 一个 `use:` 指令 */
	export interface UseDirective extends BaseNode {
		type: 'UseDirective';
		/** `use:x` 中的 'x' */
		name: string;
		/** `use:x={y}` 中的 y */
		expression: null | Expression;
	}

	interface BaseElement extends BaseNode {
		name: string;
		attributes: Array<
			Attribute | SpreadAttribute | Directive
		>;
		fragment: Fragment;
	}

	export interface Component extends BaseElement {
		type: 'Component';
	}

	export interface TitleElement extends BaseElement {
		type: 'TitleElement';
		name: 'title';
	}

	export interface SlotElement extends BaseElement {
		type: 'SlotElement';
		name: 'slot';
	}

	export interface RegularElement extends BaseElement {
		type: 'RegularElement';
	}

	export interface SvelteBody extends BaseElement {
		type: 'SvelteBody';
		name: 'svelte:body';
	}

	export interface SvelteComponent extends BaseElement {
		type: 'SvelteComponent';
		name: 'svelte:component';
		expression: Expression;
	}

	export interface SvelteDocument extends BaseElement {
		type: 'SvelteDocument';
		name: 'svelte:document';
	}

	export interface SvelteElement extends BaseElement {
		type: 'SvelteElement';
		name: 'svelte:element';
		tag: Expression;
	}

	export interface SvelteFragment extends BaseElement {
		type: 'SvelteFragment';
		name: 'svelte:fragment';
	}

	export interface SvelteBoundary extends BaseElement {
		type: 'SvelteBoundary';
		name: 'svelte:boundary';
	}

	export interface SvelteHead extends BaseElement {
		type: 'SvelteHead';
		name: 'svelte:head';
	}

	/** 这只是解析时的中间表示，最终 AST 中不存在 */
	export interface SvelteOptionsRaw extends BaseElement {
		type: 'SvelteOptions';
		name: 'svelte:options';
	}

	export interface SvelteSelf extends BaseElement {
		type: 'SvelteSelf';
		name: 'svelte:self';
	}

	export interface SvelteWindow extends BaseElement {
		type: 'SvelteWindow';
		name: 'svelte:window';
	}

	/** 一个 `{#each ...}` 块 */
	export interface EachBlock extends BaseNode {
		type: 'EachBlock';
		expression: Expression;
		/** `{#each item as entry}` 中的 `entry`。如果 `as` 部分被省略，则为 `null` */
		context: Pattern | null;
		body: Fragment;
		fallback?: Fragment;
		index?: string;
		key?: Expression;
	}

	/** 一个 `{#if ...}` 块 */
	export interface IfBlock extends BaseNode {
		type: 'IfBlock';
		elseif: boolean;
		test: Expression;
		consequent: Fragment;
		alternate: Fragment | null;
	}

	/** 一个 `{#await ...}` 块 */
	export interface AwaitBlock extends BaseNode {
		type: 'AwaitBlock';
		expression: Expression;
		// TODO 我们能否/应该将这些移动到 ThenBlock 和 CatchBlock 内部？
		/** `then` 块中的解析值 */
		value: Pattern | null;
		/** `catch` 块中的拒绝原因 */
		error: Pattern | null;
		pending: Fragment | null;
		then: Fragment | null;
		catch: Fragment | null;
	}

	export interface KeyBlock extends BaseNode {
		type: 'KeyBlock';
		expression: Expression;
		fragment: Fragment;
	}

	export interface SnippetBlock extends BaseNode {
		type: 'SnippetBlock';
		expression: Identifier;
		parameters: Pattern[];
		body: Fragment;
	}

	export interface Attribute extends BaseNode {
		type: 'Attribute';
		name: string;
		/**
		 * 引号/字符串值由数组表示，即使它们只包含一个像 `"{x}"` 的表达式
		 */
		value:
			| true
			| ExpressionTag
			| Array<Text | ExpressionTag>;
	}

	export interface SpreadAttribute extends BaseNode {
		type: 'SpreadAttribute';
		expression: Expression;
	}

	export interface Script extends BaseNode {
		type: 'Script';
		context: 'default' | 'module';
		content: Program;
		attributes: Attribute[];
	}

	export type AttributeLike =
		| Attribute
		| SpreadAttribute
		| Directive;

	export type Directive =
		| AST.AnimateDirective
		| AST.BindDirective
		| AST.ClassDirective
		| AST.LetDirective
		| AST.OnDirective
		| AST.StyleDirective
		| AST.TransitionDirective
		| AST.UseDirective;

	export type Block =
		| AST.EachBlock
		| AST.IfBlock
		| AST.AwaitBlock
		| AST.KeyBlock
		| AST.SnippetBlock;

	export type ElementLike =
		| AST.Component
		| AST.TitleElement
		| AST.SlotElement
		| AST.RegularElement
		| AST.SvelteBody
		| AST.SvelteBoundary
		| AST.SvelteComponent
		| AST.SvelteDocument
		| AST.SvelteElement
		| AST.SvelteFragment
		| AST.SvelteHead
		| AST.SvelteOptionsRaw
		| AST.SvelteSelf
		| AST.SvelteWindow
		| AST.SvelteBoundary;

	export type Tag =
		| AST.ExpressionTag
		| AST.HtmlTag
		| AST.ConstTag
		| AST.DebugTag
		| AST.RenderTag;

	export type TemplateNode =
		| AST.Root
		| AST.Text
		| Tag
		| ElementLike
		| AST.Attribute
		| AST.SpreadAttribute
		| Directive
		| AST.Comment
		| Block;

	export type SvelteNode =
		| Node
		| TemplateNode
		| AST.Fragment
		| _CSS.Node;

	export type { _CSS as CSS };
}

CompileError

interface CompileError extends ICompileDiagnostic {}

CompileOptions

interface CompileOptions extends ModuleCompileOptions {…}
name?: string;

设置生成的 JavaScript 类的名称（如果与作用域中的其他变量冲突，编译器会重命名它）。如果未指定，将从 filename 推断。

customElement?: boolean;
  • 默认 false

如果为 true，则告知编译器生成自定义元素构造函数，而不是常规 Svelte 组件。

accessors?: boolean;
  • 默认 false
  • 已弃用 在符文模式下将没有效果

如果为 true，将为组件的 props 创建 getter 和 setter。如果为 false，则仅会为只读的导出值（即用 const、class 和 function 声明的值）创建。如果使用 customElement: true 编译，此选项默认设置为 true。

namespace?: Namespace;
  • 默认 'html'

元素的命名空间，例如 "html"、"svg"、"mathml"。

immutable?: boolean;
  • 默认 false
  • 已弃用 在符文模式下将没有效果

如果为 true，则告知编译器您承诺不改变任何对象。 这允许编译器在检查值是否已更改时不那么保守。

css?: 'injected' | 'external';
  • 'injected'：样式将在使用 render(...) 时包含在 head 中，并在组件挂载时注入文档中（如果尚未存在）。对于编译为自定义元素的组件，样式会注入到影子根中。
  • 'external'：CSS 将仅在编译结果的 css 字段中返回。大多数 Svelte 打包插件将把这设置为 'external' 并使用静态生成的 CSS，以提高性能，因为这样可以生成更小的 JavaScript 包，输出可以作为可缓存的 .css 文件提供。 在使用 customElement 模式编译时，它始终为 'injected'。
cssHash?: CssHashGetter;
  • 默认 undefined

一个函数，接受一个 { hash, css, name, filename } 参数，返回用于作为作用域 CSS 的类名的字符串。 默认将返回 svelte-${hash(css)}。

preserveComments?: boolean;
  • 默认 false

如果为 true，HTML 注释将在输出中保留。默认情况下，它们会被剥离。

preserveWhitespace?: boolean;
  • 默认 false

如果为 true，元素内部和元素之间的空格将按您输入的样子保留，而不是被删除或压缩为一个空格。

runes?: boolean | undefined;
  • 默认 undefined

将其设置为 true 以强制编译器进入符文模式，即使没有符文使用的指示。 将其设置为 false 以强制编译器忽略符文，即使有符文使用的指示。 将其设置为 undefined（默认）以根据组件代码推断符文模式。 对用 Svelte 编译的 JS/TS 模块，这始终为 true。 在 Svelte 6 中将默认设置为 true。 请注意，在您的 svelte.config.js 中将其设置为 true 将为整个项目强制符文模式，包括 node_modules 中的组件，这可能不是您想要的。如果您使用 Vite，考虑转而使用 dynamicCompileOptions。

discloseVersion?: boolean;
  • 默认 true

如果为 true，通过将其添加到存储在全局 window.__svelte.v 的 Set 中，可以在浏览器中暴露 Svelte 主版本。

compatibility?: {…}
  • 已弃用 仅将这些用作迁移代码之前的临时解决方案
componentApi?: 4 | 5;
  • 默认 5

应用一种转换，使得 Svelte 文件的默认导出仍然可以像在 Svelte 4 中一样实例化——在针对浏览器编译时作为类（就像在 svelte/legacy 中使用 createClassComponent(MyComponent, {...})），或在针对服务器编译时作为带有 .render(...) 方法的对象。

sourcemap?: object | string;
  • 默认 null

一个初始源映射，将合并到最终输出的源映射中。 通常这是预处理器的源映射。

outputFilename?: string;
  • 默认 null

用于您的 JavaScript 源映射。

cssOutputFilename?: string;
  • 默认 null

用于您的 CSS 源映射。

hmr?: boolean;
  • 默认 false

如果为 true，则生成支持热重载的组件。

modernAst?: boolean;
  • 默认 false

如果为 true，则返回现代版本的 AST。 在 Svelte 6 中将默认设置为 true，并将在 Svelte 7 中删除该选项。

CompileResult

compile 从 svelte/compiler 的返回值。

interface CompileResult {…}
js: {…}

编译后的 JavaScript

code: string;

生成的代码

map: SourceMap;

一个源映射

css: null | {
	/** 生成的代码 */
	code: string;
	/** 一个源映射 */
	map: SourceMap;
};

编译后的 CSS

warnings: Warning[];

在编译过程中生成的警告对象数组。每个警告具有几个属性：

  • code 是标识警告类别的字符串
  • message 用人类可读的语言描述问题
  • start 和 end，如果警告与特定位置有关，则是具有 line、column 和 character 属性的对象
metadata: {…}

关于编译组件的元数据

runes: boolean;

指示文件是以符文模式编译的，无论是由于显式选项还是根据使用推断的。 对于 compileModule，这始终为 true。

ast: any;

AST

MarkupPreprocessor

一个标记预处理器，接受一段代码字符串并返回处理后的版本。

type MarkupPreprocessor = (options: {
	/**
	 * 整个 Svelte 文件内容
	 */
	content: string;
	/**
	 * Svelte 文件的文件名
	 */
	filename?: string;
}) => Processed | void | Promise<Processed | void>;

ModuleCompileOptions

interface ModuleCompileOptions {…}
dev?: boolean;
  • 默认 false

如果为 true，则会添加额外的代码，在开发期间执行运行时检查并提供调试信息。

generate?: 'client' | 'server' | false;
  • 默认 'client'

如果为 "client"，则 Svelte 生成的代码设计为在浏览器中运行。 如果为 "server"，则 Svelte 生成的代码适合服务器端渲染。 如果为 false，则不生成任何内容。对于只关注警告的工具非常有用。

filename?: string;

用于调试提示和源映射。您的打包插件将自动设置。

rootDir?: string;
  • 默认 process.cwd() 在 node 类环境下，其他地方为 undefined

用于确保文件名不会泄露文件系统信息。您的打包插件将自动设置。

warningFilter?: (warning: Warning) => boolean;

一个接受 Warning 作为参数并返回布尔值的函数。 使用此方法过滤警告。返回 true 以保留警告，返回 false 以丢弃它。

Preprocessor

一个脚本/样式预处理器，接受一段代码字符串并返回处理后的版本。

type Preprocessor = (options: {
	/**
	 * 脚本/样式标签内容
	 */
	content: string;
	/**
	 * 脚本/样式标签上的属性
	 */
	attributes: Record<string, string | boolean>;
	/**
	 * 整个 Svelte 文件内容
	 */
	markup: string;
	/**
	 * Svelte 文件的文件名
	 */
	filename?: string;
}) => Processed | void | Promise<Processed | void>;

PreprocessorGroup

预处理器组是一组应用于 Svelte 文件的预处理器。

interface PreprocessorGroup {…}
name?: string;

预处理器的名称。将在下一个主要版本中成为必需选项。

markup?: MarkupPreprocessor;
style?: Preprocessor;
script?: Preprocessor;

Processed

预处理器运行的结果。如果预处理器未返回结果，则假定代码未更改。

interface Processed {…}
code: string;

新代码

map?: string | object;

一个源映射，映射回原始代码

dependencies?: string[];

一个要监视变更的附加文件列表

attributes?: Record<string, string | boolean>;

仅适用于脚本/样式预处理器：要设置在标签上的更新属性。如果未定义，则属性保持不变。

toString?: () => string;

Warning

interface Warning extends ICompileDiagnostic {}

在 GitHub 编辑此页面

上一页 下一页
svelte/animate