svelte/compiler

通常，你不会直接与 Svelte 编译器交互，而是会使用打包器插件将其集成到构建系统中。Svelte 团队最推荐并投入最多的打包器插件是 vite-plugin-svelte。SvelteKit 框架提供了一个利用 vite-plugin-svelte 构建应用程序的设置，以及一个 打包 Svelte 组件库的工具。Svelte Society 维护了一个 其他打包器插件 列表，用于 Rollup 和 Webpack 等其他工具。

尽管如此，了解如何使用编译器很有用，因为打包器插件通常会向你公开编译器选项。

compile永久链接

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

这是魔术发生的地方。svelte.compile 采用你的组件源代码，并将其转换为导出类的 JavaScript 模块。

ts
import { compile } from 'svelte/compiler';

const result = compile(source, {
	// options
});

请参阅 CompileOptions 以了解所有可用选项。

返回的 result 对象包含组件的代码以及有用的元数据。

ts
const { js, css, ast, warnings, vars, stats } = compile(source);

请参阅 CompileResult 以获取编译结果的完整说明。

parse永久链接

ts
function parse(
	template: string,
	options?: ParserOptions
): Ast;

parse 函数解析组件，仅返回其抽象语法树。与使用 generate: false 选项进行编译不同，除了解析组件之外，它不会执行任何验证或其他分析。请注意，返回的 AST 不被视为公共 API，因此随时可能发生重大更改。

ts
import { parse } from 'svelte/compiler';

const ast = parse(source, { filename: 'App.svelte' });

preprocess永久链接

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

一些 官方和社区维护的预处理插件 可用于让你将 Svelte 与 TypeScript、PostCSS、SCSS 和 Less 等工具配合使用。

你可以使用 svelte.preprocess API 编写自己的预处理器。

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

第一个参数是组件源代码。第二个参数是预处理器数组（或单个预处理器，如果你只有一个），其中预处理器是一个对象，它具有必需的 name 以及可选的 markup、script 和 style 函数。

markup 函数接收整个组件源文本以及组件的 filename（如果在第三个参数中指定了该名称）。

script 和 style 函数分别接收 <script> 和 <style> 元素的内容（content）以及整个组件源文本（markup）。除了 filename 之外，它们还会获取一个元素属性对象。

每个 markup、script 或 style 函数都必须返回一个对象（或解析为对象的 Promise），该对象具有 code 属性，表示转换后的源代码。它们可以选择返回 dependencies 数组，该数组表示要监视其更改的文件，以及 map 对象，该对象是将转换映射回原始代码的源映射。script 和 style 预处理器可以选择返回一个属性记录，该记录表示脚本/样式标签上的更新属性。

预处理器函数应尽可能返回 map 对象，否则调试将变得更加困难，因为堆栈跟踪无法正确链接到原始代码。

ts
import { preprocess } from 'svelte/compiler';
import MagicString from 'magic-string';

const { code } = await preprocess(
	source,
	{
		markup: ({ content, filename }) => {
			const pos = content.indexOf('foo');
			if (pos < 0) {
				return { code: content };
			}
			const s = new MagicString(content, { filename });
			s.overwrite(pos, pos + 3, 'bar', { storeName: true });
			return {
				code: s.toString(),
				map: s.generateMap()
			};
		}
	},
	{
		filename: 'App.svelte'
	}
);

如果返回 dependencies 数组，它将包含在结果对象中。这被 vite-plugin-svelte 和 rollup-plugin-svelte 等包使用，以监视其他文件的更改，例如，当你的 <style> 标签具有 @import（例如）。

ts
import { preprocess } from 'svelte/compiler';
import MagicString from 'magic-string';
Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.2322Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.
import sass from 'sass';
import { dirname } from 'path';
Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
  Type 'undefined' is not assignable to type 'string'.2345Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
  Type 'undefined' is not assignable to type 'string'.

const { code } = await preprocess(
	source,
	{
		name: 'my-fancy-preprocessor',
		markup: ({ content, filename }) => {
			// Return code as is when no foo string present
			const pos = content.indexOf('foo');
			if (pos < 0) {
				return;
			}

			// Replace foo with bar using MagicString which provides
			// a source map along with the changed code
			const s = new MagicString(content, { filename });
			s.overwrite(pos, pos + 3, 'bar', { storeName: true });

			return {
				code: s.toString(),
				map: s.generateMap({ hires: true, file: filename })
			};
		},
		style: async ({ content, attributes, filename }) => {
			// only process <style lang="sass">
			if (attributes.lang !== 'sass') return;

			const { css, stats } = await new Promise((resolve, reject) =>
				sass.render(
					{
						file: filename,
						data: content,
						includePaths: [dirname(filename)]
					},
					(err, result) => {
						if (err) reject(err);
						else resolve(result);
					}
				)
			);

			// remove lang attribute from style tag
			delete attributes.lang;

			return {
				code: css.toString(),
				dependencies: stats.includedFiles,
				attributes
			};
		}
	},
	{
		filename: 'App.svelte'
	}
);

多个预处理器可以一起使用。第一个的输出成为第二个的输入。在一个预处理器中，markup 首先运行，然后是 script 和 style。

在 Svelte 3 中，所有 markup 函数首先运行，然后是所有 script，最后是所有 style 预处理器。此顺序在 Svelte 4 中已更改。

ts
import { preprocess } from 'svelte/compiler';

const { code } = await preprocess(source, [
	{
		name: 'first preprocessor',
		markup: () => {
			console.log('this runs first');
		},
		script: () => {
			console.log('this runs second');
		},
		style: () => {
			console.log('this runs third');
		}
	},
	{
		name: 'second preprocessor',
		markup: () => {
			console.log('this runs fourth');
		},
		script: () => {
			console.log('this runs fifth');
		},
		style: () => {
			console.log('this runs sixth');
		}
	}
], {
	filename: 'App.svelte'
});

ts
import { preprocess } from 'svelte/compiler';

const { code } = await preprocess(
	source,
	[
		{
			name: 'first preprocessor',
			markup: () => {
				console.log('this runs first');
			},
			script: () => {
				console.log('this runs second');
			},
			style: () => {
				console.log('this runs third');
			},
		},
		{
			name: 'second preprocessor',
			markup: () => {
				console.log('this runs fourth');
			},
			script: () => {
				console.log('this runs fifth');
			},
			style: () => {
				console.log('this runs sixth');
			},
		},
	],
	{
		filename: 'App.svelte',
	},
);

walk永久链接

walk 函数提供了一种使用编译器自己的内置 estree-walker 实例遍历解析器生成的抽象语法树的方法。

遍历器获取要遍历的抽象语法树和一个具有两个可选方法的对象：enter 和 leave。对于每个节点，都会调用 enter（如果存在）。然后，除非在 enter 期间调用 this.skip()，否则将遍历每个子节点，然后在节点上调用 leave。

ts
import { walk } from 'svelte/compiler';

walk(ast, {
	enter(node, parent, prop, index) {
		do_something(node);
		if (should_skip_children(node)) {
			this.skip();
		}
	},
	leave(node, parent, prop, index) {
		do_something_else(node);
	}
});

ts
import { walk } from 'svelte/compiler';

walk(ast, {
	enter(node, parent, prop, index) {
		do_something(node);
		if (should_skip_children(node)) {
			this.skip();
		}
	},
	leave(node, parent, prop, index) {
		do_something_else(node);
	},
});

VERSION永久链接

ts
const VERSION: string;

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

ts
import { VERSION } from 'svelte/compiler';
console.log(`running svelte version ${VERSION}`);

类型永久链接

CompileOptions永久链接

ts
interface CompileOptions {…}

ts
name?: string;

ts
filename?: string;

ts
generate?: 'dom' | 'ssr' | false;

ts
errorMode?: 'throw' | 'warn';

ts
varsReport?: 'full' | 'strict' | false;

ts
sourcemap?: object | string;

ts
enableSourcemap?: EnableSourcemap;

ts
outputFilename?: string;

ts
cssOutputFilename?: string;

ts
sveltePath?: string;

ts
dev?: boolean;

ts
accessors?: boolean;

ts
immutable?: boolean;

ts
hydratable?: boolean;

ts
legacy?: boolean;

ts
customElement?: boolean;

ts
tag?: string;

ts
css?: 'injected' | 'external' | 'none' | boolean;

ts
loopGuardTimeout?: number;

ts
namespace?: string;

ts
cssHash?: CssHashGetter;

ts
preserveComments?: boolean;

ts
preserveWhitespace?: boolean;

ts
discloseVersion?: boolean;

CompileResult永久链接

从 svelte/compiler 中 compile 返回的形状

ts
interface CompileResult {…}

ts
js: {…}

ts
code: string;

ts
map: any;

ts
css: CssResult;

ts
ast: Ast;

ts
warnings: Warning[];

ts
vars: Var[];

ts
stats: {
	timings: {
		total: number;
	};
};

CssHashGetter永久链接

ts
type CssHashGetter = (args: {
	name: string;
	filename: string | undefined;
	css: string;
	hash: (input: string) => string;
}) => string;

EnableSourcemap永久链接

ts
type EnableSourcemap =
	| boolean
	| { js: boolean; css: boolean };

MarkupPreprocessor永久链接

一个标记预处理器，它获取一个代码字符串并返回一个经过处理的版本。

ts
type MarkupPreprocessor = (options: {
	/**
	 * The whole Svelte file content
	 */
	content: string;
	/**
	 * The filename of the Svelte file
	 */
	filename?: string;
}) => Processed | void | Promise<Processed | void>;

Preprocessor永久链接

一个脚本/样式预处理器，它获取一个代码字符串并返回一个经过处理的版本。

ts
type Preprocessor = (options: {
	/**
	 * The script/style tag content
	 */
	content: string;
	/**
	 * The attributes on the script/style tag
	 */
	attributes: Record<string, string | boolean>;
	/**
	 * The whole Svelte file content
	 */
	markup: string;
	/**
	 * The filename of the Svelte file
	 */
	filename?: string;
}) => Processed | void | Promise<Processed | void>;

PreprocessorGroup永久链接

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

ts
interface PreprocessorGroup {…}

ts
name?: string;

ts
markup?: MarkupPreprocessor;

ts
style?: Preprocessor;

ts
script?: Preprocessor;

Processed永久链接

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

ts
interface Processed {…}

ts
code: string;

ts
map?: string | object;

ts
dependencies?: string[];

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

ts
toString?: () => string;

SveltePreprocessor永久链接

实用程序类型，用于从预处理器组中提取预处理器的类型

ts
interface SveltePreprocessor<
	PreprocessorType extends keyof PreprocessorGroup,
	Options = any
> {…}

ts
(options?: Options): Required<Pick<PreprocessorGroup, PreprocessorType>>;