远程函数
自 2.27 起可用
¥Available since 2.27
远程函数是客户端和服务器之间进行类型安全通信的工具。它们可以在应用的任何位置调用,但始终在服务器上运行,这意味着它们可以安全地访问包含环境变量和数据库客户端等内容的 服务器专用模块。
¥Remote functions are a tool for type-safe communication between client and server. They can be called anywhere in your app, but always run on the server, meaning they can safely access server-only modules containing things like environment variables and database clients.
结合 Svelte 对 await
的实验性支持,它允许你直接在组件内部加载和操作数据。
¥Combined with Svelte’s experimental support for await
, it allows you to load and manipulate data directly inside your components.
此功能目前处于实验阶段,这意味着它可能包含错误,并且可能会随时更改,恕不另行通知。你必须在 svelte.config.js
中添加 kit.experimental.remoteFunctions
选项来启用此功能:
¥This feature is currently experimental, meaning it is likely to contain bugs and is subject to change without notice. You must opt in by adding the kit.experimental.remoteFunctions
option in your svelte.config.js
:
export default {
kit: {
experimental: {
remoteFunctions: boolean;
};
}
kit: {
experimental: {
remoteFunctions: boolean;
}
experimental: {
remoteFunctions: boolean
remoteFunctions: true
}
}
};
概述(Overview)
¥Overview
远程函数从 .remote.js
或 .remote.ts
文件导出,有四种形式:query
、form
、command
和 prerender
。在客户端,导出的函数将转换为 fetch
封装器,并通过生成的 HTTP 端点调用服务器上的对应函数。远程文件必须放在 lib
或 routes
目录中。
¥Remote functions are exported from a .remote.js
or .remote.ts
file, and come in four flavours: query
, form
, command
and prerender
. On the client, the exported functions are transformed to fetch
wrappers that invoke their counterparts on the server via a generated HTTP endpoint. Remote files must be placed in the lib
or routes
directory.
query
query
函数允许你从服务器读取动态数据(对于静态数据,请考虑使用 prerender
):
¥The query
function allows you to read dynamic data from the server (for static data, consider using prerender
instead):
import { function query<Output>(fn: () => MaybePromise<Output>): RemoteQueryFunction<void, Output> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
export const const getPosts: RemoteQueryFunction<void, any[]>
getPosts = query<any[]>(fn: () => MaybePromise<any[]>): RemoteQueryFunction<void, any[]> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(async () => {
const const posts: any[]
posts = await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
SELECT title, slug
FROM post
ORDER BY published_at
DESC
`;
return const posts: any[]
posts;
});
在整个页面中,你将看到从
$lib/server/database
和$lib/server/auth
等虚构模块导入的内容。这些导入纯粹是为了说明目的 - 你可以使用任何你喜欢的数据库客户端和身份验证设置。上面的
db.sql
函数是一个 tagged template function,它会转义任何插值。
从 getPosts
返回的查询将作为解析为 posts
的 Promise
元素运行:
¥The query returned from getPosts
works as a Promise
that resolves to posts
:
<script>
import { getPosts } from './data.remote';
</script>
<h1>Recent posts</h1>
<ul>
{#each await getPosts() as { title, slug }}
<li><a href="/blog/{slug}">{title}</a></li>
{/each}
</ul>
<script lang="ts">
import { getPosts } from './data.remote';
</script>
<h1>Recent posts</h1>
<ul>
{#each await getPosts() as { title, slug }}
<li><a href="/blog/{slug}">{title}</a></li>
{/each}
</ul>
在 Promise 解析之前(如果出现错误),将调用最近的 <svelte:boundary>
。
¥Until the promise resolves — and if it errors — the nearest <svelte:boundary>
will be invoked.
虽然建议使用 await
,但查询也可以使用 loading
、error
和 current
属性:
¥While using await
is recommended, as an alternative the query also has loading
, error
and current
properties:
<script>
import { getPosts } from './data.remote';
const query = getPosts();
</script>
{#if query.error}
<p>oops!</p>
{:else if query.loading}
<p>loading...</p>
{:else}
<ul>
{#each query.current as { title, slug }}
<li><a href="/blog/{slug}">{title}</a></li>
{/each}
</ul>
{/if}
<script lang="ts">
import { getPosts } from './data.remote';
const query = getPosts();
</script>
{#if query.error}
<p>oops!</p>
{:else if query.loading}
<p>loading...</p>
{:else}
<ul>
{#each query.current as { title, slug }}
<li><a href="/blog/{slug}">{title}</a></li>
{/each}
</ul>
{/if}
在本文档的其余部分,我们将使用
await
形式。
查询参数(Query arguments)
¥Query arguments
查询函数可以接受参数,例如单个帖子的 slug
:
¥Query functions can accept an argument, such as the slug
of an individual post:
<script>
import { getPost } from '../data.remote';
let { params } = $props();
const post = $derived(await getPost(params.slug));
</script>
<h1>{post.title}</h1>
<div>{@html post.content}</div>
<script lang="ts">
import { getPost } from '../data.remote';
let { params } = $props();
const post = $derived(await getPost(params.slug));
</script>
<h1>{post.title}</h1>
<div>{@html post.content}</div>
由于 getPost
暴露了一个 HTTP 端点,因此验证此参数以确保其类型正确非常重要。为此,我们可以使用任何 标准架构 验证库,例如 Zod 或 Valibot:
¥Since getPost
exposes an HTTP endpoint, it’s important to validate this argument to be sure that it’s the correct type. For this, we can use any Standard Schema validation library such as Zod or Valibot:
import * as import v
v from 'valibot';
import { function error(status: number, body: App.Error): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error } from '@sveltejs/kit';
import { function query<Output>(fn: () => MaybePromise<Output>): RemoteQueryFunction<void, Output> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
export const const getPosts: RemoteQueryFunction<void, void>
getPosts = query<void>(fn: () => MaybePromise<void>): RemoteQueryFunction<void, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(async () => { /* ... */ });
export const const getPost: RemoteQueryFunction<string, any>
getPost = query<v.StringSchema<undefined>, any>(schema: v.StringSchema<undefined>, fn: (arg: string) => any): RemoteQueryFunction<string, any> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (slug: string
slug) => {
const [const post: any
post] = await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
SELECT * FROM post
WHERE slug = ${slug: string
slug}
`;
if (!const post: any
post) function error(status: number, body?: {
message: string;
} extends App.Error ? App.Error | string | undefined : never): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error(404, 'Not found');
return const post: any
post;
});
参数和返回值都使用 devalue 序列化,除了 JSON 之外,它还处理 Date
和 Map
等类型(以及 传输钩子 中定义的自定义类型)。
¥Both the argument and the return value are serialized with devalue, which handles types like Date
and Map
(and custom types defined in your transport hook) in addition to JSON.
刷新查询(Refreshing queries)
¥Refreshing queries
任何查询都可以通过其 refresh
方法进行更新:
¥Any query can be updated via its refresh
method:
<button onclick={() => getPosts().refresh()}>
Check for new posts
</button>
查询在页面上时会被缓存,也就是
getPosts() === getPosts()
。这意味着你不需要像const posts = getPosts()
这样的引用来刷新查询。
form
form
函数可以轻松地将数据写入服务器。它需要一个回调函数,该回调函数接收当前的 FormData
……
¥The form
function makes it easy to write data to the server. It takes a callback that receives the current FormData
...
import * as import v
v from 'valibot';
import { function error(status: number, body: App.Error): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error, function redirect(status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | ({} & number), location: string | URL): never
Redirect a request. When called during request handling, SvelteKit will return a redirect response.
Make sure you’re not catching the thrown redirect, which would prevent SvelteKit from handling it.
Most common status codes:
303 See Other
: redirect as a GET request (often used after a form POST request)
307 Temporary Redirect
: redirect will keep the request method
308 Permanent Redirect
: redirect will keep the request method, SEO will be transferred to the new page
redirect } from '@sveltejs/kit';
import { function query<Output>(fn: () => MaybePromise<Output>): RemoteQueryFunction<void, Output> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query, function form<T>(fn: (data: FormData) => MaybePromise<T>): RemoteForm<T>
Creates a form object that can be spread onto a <form>
element.
See Remote functions for full documentation.
form } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
import * as module "$lib/server/auth"
auth from '$lib/server/auth';
export const const getPosts: RemoteQueryFunction<void, void>
getPosts = query<void>(fn: () => MaybePromise<void>): RemoteQueryFunction<void, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(async () => { /* ... */ });
export const const getPost: RemoteQueryFunction<string, void>
getPost = query<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>): RemoteQueryFunction<string, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (slug: string
slug) => { /* ... */ });
export const const createPost: RemoteForm<never>
createPost = form<never>(fn: (data: FormData) => Promise<never>): RemoteForm<never>
Creates a form object that can be spread onto a <form>
element.
See Remote functions for full documentation.
form(async (data: FormData
data) => {
// Check the user is logged in
const const user: auth.User | null
user = await module "$lib/server/auth"
auth.function getUser(): Promise<auth.User | null>
Gets a user’s info from their cookies, using getRequestEvent
getUser();
if (!const user: auth.User | null
user) function error(status: number, body?: {
message: string;
} extends App.Error ? App.Error | string | undefined : never): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error(401, 'Unauthorized');
const const title: FormDataEntryValue | null
title = data: FormData
data.FormData.get(name: string): FormDataEntryValue | null
get('title');
const const content: FormDataEntryValue | null
content = data: FormData
data.FormData.get(name: string): FormDataEntryValue | null
get('content');
// Check the data is valid
if (typeof const title: FormDataEntryValue | null
title !== 'string' || typeof const content: FormDataEntryValue | null
content !== 'string') {
function error(status: number, body?: {
message: string;
} extends App.Error ? App.Error | string | undefined : never): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error(400, 'Title and content are required');
}
const const slug: string
slug = const title: string
title.String.toLowerCase(): string
Converts all the alphabetic characters in a string to lowercase.
toLowerCase().String.replace(searchValue: {
[Symbol.replace](string: string, replaceValue: string): string;
}, replaceValue: string): string (+3 overloads)
Passes a string and
{@linkcode
replaceValue
}
to the [Symbol.replace]
method on
{@linkcode
searchValue
}
. This method is expected to implement its own replacement algorithm.
replace(/ /g, '-');
// Insert into the database
await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
INSERT INTO post (slug, title, content)
VALUES (${const slug: string
slug}, ${const title: string
title}, ${const content: string
content})
`;
// Redirect to the newly created page
function redirect(status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | ({} & number), location: string | URL): never
Redirect a request. When called during request handling, SvelteKit will return a redirect response.
Make sure you’re not catching the thrown redirect, which would prevent SvelteKit from handling it.
Most common status codes:
303 See Other
: redirect as a GET request (often used after a form POST request)
307 Temporary Redirect
: redirect will keep the request method
308 Permanent Redirect
: redirect will keep the request method, SEO will be transferred to the new page
redirect(303, `/blog/${const slug: string
slug}`);
});
...并返回一个可以展开到 <form>
元素上的对象。每当表单提交时,都会调用回调。
¥...and returns an object that can be spread onto a <form>
element. The callback is called whenever the form is submitted.
<script>
import { createPost } from '../data.remote';
</script>
<h1>Create a new post</h1>
<form {...createPost}>
<label>
<h2>Title</h2>
<input name="title" />
</label>
<label>
<h2>Write your post</h2>
<textarea name="content"></textarea>
</label>
<button>Publish!</button>
</form>
<script lang="ts">
import { createPost } from '../data.remote';
</script>
<h1>Create a new post</h1>
<form {...createPost}>
<label>
<h2>Title</h2>
<input name="title" />
</label>
<label>
<h2>Write your post</h2>
<textarea name="content"></textarea>
</label>
<button>Publish!</button>
</form>
表单对象包含 method
和 action
属性,使其无需 JavaScript 即可工作(即提交数据并重新加载页面)。它还包含一个 onsubmit
处理程序,可在 JavaScript 可用时逐步增强表单,提交数据时无需重新加载整个页面。
¥The form object contains method
and action
properties that allow it to work without JavaScript (i.e. it submits data and reloads the page). It also has an onsubmit
handler that progressively enhances the form when JavaScript is available, submitting data without reloading the entire page.
单次修改(Single-flight mutations)
¥Single-flight mutations
默认情况下,页面上使用的所有查询(以及任何 load
函数)都是表单提交成功后自动刷新。这确保所有内容都是最新的,但效率也较低:许多查询将保持不变,并且需要再次访问服务器才能获取更新的数据。
¥By default, all queries used on the page (along with any load
functions) are automatically refreshed following a successful form submission. This ensures that everything is up-to-date, but it’s also inefficient: many queries will be unchanged, and it requires a second trip to the server to get the updated data.
相反,我们可以指定哪些查询应该在响应特定表单提交时刷新。这称为单次飞行突变,有两种方法可以实现它。第一个函数是在表单处理程序内部刷新服务器上的查询:
¥Instead, we can specify which queries should be refreshed in response to a particular form submission. This is called a single-flight mutation, and there are two ways to achieve it. The first is to refresh the query on the server, inside the form handler:
export const const getPosts: RemoteQueryFunction<void, void>
getPosts = query<void>(fn: () => MaybePromise<void>): RemoteQueryFunction<void, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(async () => { /* ... */ });
export const const getPost: RemoteQueryFunction<string, void>
getPost = query<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>): RemoteQueryFunction<string, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (slug: string
slug) => { /* ... */ });
export const const createPost: RemoteForm<never>
createPost = form<never>(fn: (data: FormData) => Promise<never>): RemoteForm<never>
Creates a form object that can be spread onto a <form>
element.
See Remote functions for full documentation.
form(async (data: FormData
data) => {
// form logic goes here...
// Refresh `getPosts()` on the server, and send
// the data back with the result of `createPost`
await const getPosts: (arg: void) => RemoteQuery<void>
getPosts().function refresh(): Promise<void>
On the client, this function will re-fetch the query from the server.
On the server, this can be called in the context of a command
or form
and the refreshed data will accompany the action response back to the client.
This prevents SvelteKit needing to refresh all queries on the page in a second server round-trip.
refresh();
// Redirect to the newly created page
function redirect(status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | ({} & number), location: string | URL): never
Redirect a request. When called during request handling, SvelteKit will return a redirect response.
Make sure you’re not catching the thrown redirect, which would prevent SvelteKit from handling it.
Most common status codes:
303 See Other
: redirect as a GET request (often used after a form POST request)
307 Temporary Redirect
: redirect will keep the request method
308 Permanent Redirect
: redirect will keep the request method, SEO will be transferred to the new page
redirect(303, `/blog/${const slug: ""
slug}`);
});
第二个函数是从客户端驱动单次飞行突变,我们将在 enhance
部分中看到这一点。
¥The second is to drive the single-flight mutation from the client, which we’ll see in the section on enhance
.
返回和重定向(Returns and redirects)
¥Returns and redirects
上述示例使用了 redirect(...)
元素,它将用户引导至新创建的页面。或者,回调可以返回数据,在这种情况下,它将作为 createPost.result
使用:
¥The example above uses redirect(...)
, which sends the user to the newly created page. Alternatively, the callback could return data, in which case it would be available as createPost.result
:
export const const createPost: RemoteForm<{
success: boolean;
}>
createPost = form<{
success: boolean;
}>(fn: (data: FormData) => MaybePromise<{
success: boolean;
}>): RemoteForm<{
success: boolean;
}>
Creates a form object that can be spread onto a <form>
element.
See Remote functions for full documentation.
form(async (data: FormData
data) => {
// ...
return { success: boolean
success: true };
});
<script>
import { createPost } from '../data.remote';
</script>
<h1>Create a new post</h1>
<form {...createPost}><!-- ... --></form>
{#if createPost.result?.success}
<p>Successfully published!</p>
{/if}
<script lang="ts">
import { createPost } from '../data.remote';
</script>
<h1>Create a new post</h1>
<form {...createPost}><!-- ... --></form>
{#if createPost.result?.success}
<p>Successfully published!</p>
{/if}
此值是短暂的 - 如果你重新提交、离开或重新加载页面,它将消失。
¥This value is ephemeral — it will vanish if you resubmit, navigate away, or reload the page.
result
值不一定表示成功 - 它也可以包含验证错误,以及任何需要在页面重新加载时重新填充表单的数据。
如果提交过程中出现错误,则会渲染最近的 +error.svelte
页面。
¥If an error occurs during submission, the nearest +error.svelte
page will be rendered.
enhance
我们可以使用 enhance
方法自定义表单提交时的操作:
¥We can customize what happens when the form is submitted with the enhance
method:
<script>
import { createPost } from '../data.remote';
import { showToast } from '$lib/toast';
</script>
<h1>Create a new post</h1>
<form {...createPost.enhance(async ({ form, data, submit }) => {
try {
await submit();
form.reset();
showToast('Successfully published!');
} catch (error) {
showToast('Oh no! Something went wrong');
}
})}>
<input name="title" />
<textarea name="content"></textarea>
<button>publish</button>
</form>
<script lang="ts">
import { createPost } from '../data.remote';
import { showToast } from '$lib/toast';
</script>
<h1>Create a new post</h1>
<form {...createPost.enhance(async ({ form, data, submit }) => {
try {
await submit();
form.reset();
showToast('Successfully published!');
} catch (error) {
showToast('Oh no! Something went wrong');
}
})}>
<input name="title" />
<textarea name="content"></textarea>
<button>publish</button>
</form>
回调函数接收 form
元素、其包含的 data
元素以及 submit
函数。
¥The callback receives the form
element, the data
it contains, and a submit
function.
要启用客户端驱动的 单次修改,请使用 submit().updates(...)
。例如,如果此页面使用了 getPosts()
查询,我们可以像这样刷新它:
¥To enable client-driven single-flight mutations, use submit().updates(...)
. For example, if the getPosts()
query was used on this page, we could refresh it like so:
await function submit(): Promise<any> & {
updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<any>;
}
submit().function updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<any>
updates(function getPosts(): RemoteQuery<Post[]>
getPosts());
我们还可以在提交过程中覆盖当前数据:
¥We can also override the current data while the submission is ongoing:
await function submit(): Promise<any> & {
updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<any>;
}
submit().function updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<any>
updates(
function getPosts(): RemoteQuery<Post[]>
getPosts().function withOverride(update: (current: Post[]) => Post[]): RemoteQueryOverride
Temporarily override the value of a query. This is used with the updates
method of a command or enhanced form submission to provide optimistic updates.
<script>
import { getTodos, addTodo } from './todos.remote.js';
const todos = getTodos();
</script>
<form {...addTodo.enhance(async ({ data, submit }) => {
await submit().updates(
todos.withOverride((todos) => [...todos, { text: data.get('text') }])
);
}}>
<input type="text" name="text" />
<button type="submit">Add Todo</button>
</form>
withOverride((posts: Post[]
posts) => [const newPost: Post
newPost, ...posts: Post[]
posts])
);
覆盖函数将立即应用,并在提交完成(或失败)时释放。
¥The override will be applied immediately, and released when the submission completes (or fails).
buttonProps
默认情况下,提交表单会向 <form>
元素的 action
属性指定的 URL 发送请求,对于远程函数来说,该属性是 SvelteKit 生成的表单对象的一个属性。
¥By default, submitting a form will send a request to the URL indicated by the <form>
element’s action
attribute, which in the case of a remote function is a property on the form object generated by SvelteKit.
<form>
中的 <button>
可以使用 formaction
属性将请求发送到不同的 URL。例如,你可能有一个表单,它允许你根据点击的按钮来登录或注册。
¥It’s possible for a <button>
inside the <form>
to send the request to a different URL, using the formaction
attribute. For example, you might have a single form that allows you to login or register depending on which button was clicked.
此属性存在于表单对象的 buttonProps
属性中:
¥This attribute exists on the buttonProps
property of a form object:
<script>
import { login, register } from '$lib/auth';
</script>
<form {...login}>
<label>
Your username
<input name="username" />
</label>
<label>
Your password
<input name="password" type="password" />
</label>
<button>login</button>
<button {...register.buttonProps}>register</button>
</form>
<script lang="ts">
import { login, register } from '$lib/auth';
</script>
<form {...login}>
<label>
Your username
<input name="username" />
</label>
<label>
Your password
<input name="password" type="password" />
</label>
<button>login</button>
<button {...register.buttonProps}>register</button>
</form>
与表单对象本身一样,buttonProps
也有一个用于自定义提交行为的 enhance
方法。
¥Like the form object itself, buttonProps
has an enhance
method for customizing submission behaviour.
command
command
函数与 form
类似,允许你将数据写入服务器。与 form
不同,它不特定于某个元素,可以从任何地方调用。
¥The command
function, like form
, allows you to write data to the server. Unlike form
, it’s not specific to an element and can be called from anywhere.
尽可能优先使用
form
,因为如果 JavaScript 被禁用或加载失败,它会优雅地降级。
由于如果函数接受参数,则使用 query
时,通过将 标准架构 作为第一个参数传递给 command
,该参数应为 validated。
¥As with query
, if the function accepts an argument it should be validated by passing a Standard Schema as the first argument to command
.
import * as import v
v from 'valibot';
import { function query<Output>(fn: () => MaybePromise<Output>): RemoteQueryFunction<void, Output> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query, function command<Output>(fn: () => Output): RemoteCommand<void, Output> (+2 overloads)
Creates a remote command. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
command } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
export const const getLikes: RemoteQueryFunction<string, any>
getLikes = query<v.StringSchema<undefined>, any>(schema: v.StringSchema<undefined>, fn: (arg: string) => any): RemoteQueryFunction<string, any> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (id: string
id) => {
const [const row: any
row] = await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
SELECT likes
FROM item
WHERE id = ${id: string
id}
`;
return const row: any
row.likes;
});
export const const addLike: RemoteCommand<string, Promise<void>>
addLike = command<v.StringSchema<undefined>, Promise<void>>(validate: v.StringSchema<undefined>, fn: (arg: string) => Promise<void>): RemoteCommand<string, Promise<void>> (+2 overloads)
Creates a remote command. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
command(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (id: string
id) => {
await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
UPDATE item
SET likes = likes + 1
WHERE id = ${id: string
id}
`;
});
现在只需从(例如)事件处理程序调用 addLike
即可:
¥Now simply call addLike
, from (for example) an event handler:
<script>
import { getLikes, addLike } from './likes.remote';
import { showToast } from '$lib/toast';
let { item } = $props();
</script>
<button
onclick={async () => {
try {
await addLike(item.id);
} catch (error) {
showToast('Something went wrong!');
}
}}
>
add like
</button>
<p>likes: {await getLikes(item.id)}</p>
<script lang="ts">
import { getLikes, addLike } from './likes.remote';
import { showToast } from '$lib/toast';
let { item } = $props();
</script>
<button
onclick={async () => {
try {
await addLike(item.id);
} catch (error) {
showToast('Something went wrong!');
}
}}
>
add like
</button>
<p>likes: {await getLikes(item.id)}</p>
渲染期间无法调用命令。
单次修改(Single-flight mutations)
¥Single-flight mutations
与表单一样,页面上的任何查询(例如上例中的 getLikes(item.id)
)将在命令成功执行后自动刷新。但我们可以通过在命令内部告诉 SvelteKit 哪些查询将受到命令的影响来提高效率……
¥As with forms, any queries on the page (such as getLikes(item.id)
in the example above) will automatically be refreshed following a successful command. But we can make things more efficient by telling SvelteKit which queries will be affected by the command, either inside the command itself...
export const const getLikes: RemoteQueryFunction<string, void>
getLikes = query<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>): RemoteQueryFunction<string, void> (+2 overloads)
Creates a remote query. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
query(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (id: string
id) => { /* ... */ });
export const const addLike: RemoteCommand<string, Promise<void>>
addLike = command<v.StringSchema<undefined>, Promise<void>>(validate: v.StringSchema<undefined>, fn: (arg: string) => Promise<void>): RemoteCommand<string, Promise<void>> (+2 overloads)
Creates a remote command. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
command(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (id: string
id) => {
await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
UPDATE item
SET likes = likes + 1
WHERE id = ${id: string
id}
`;
const getLikes: (arg: string) => RemoteQuery<void>
getLikes(id: string
id).function refresh(): Promise<void>
On the client, this function will re-fetch the query from the server.
On the server, this can be called in the context of a command
or form
and the refreshed data will accompany the action response back to the client.
This prevents SvelteKit needing to refresh all queries on the page in a second server round-trip.
refresh();
});
...或者当我们调用它时:
¥...or when we call it:
try {
await const addLike: (arg: string) => Promise<void> & {
updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<...>;
}
addLike(const item: Item
item.Item.id: string
id).function updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<void>
updates(const getLikes: (arg: string) => RemoteQuery<number>
getLikes(const item: Item
item.Item.id: string
id));
} catch (var error: unknown
error) {
function showToast(message: string): void
showToast('Something went wrong!');
}
和以前一样,我们可以使用 withOverride
进行乐观更新:
¥As before, we can use withOverride
for optimistic updates:
try {
await const addLike: (arg: string) => Promise<void> & {
updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<...>;
}
addLike(const item: Item
item.Item.id: string
id).function updates(...queries: Array<RemoteQuery<any> | RemoteQueryOverride>): Promise<void>
updates(
const getLikes: (arg: string) => RemoteQuery<number>
getLikes(const item: Item
item.Item.id: string
id).function withOverride(update: (current: number) => number): RemoteQueryOverride
Temporarily override the value of a query. This is used with the updates
method of a command or enhanced form submission to provide optimistic updates.
<script>
import { getTodos, addTodo } from './todos.remote.js';
const todos = getTodos();
</script>
<form {...addTodo.enhance(async ({ data, submit }) => {
await submit().updates(
todos.withOverride((todos) => [...todos, { text: data.get('text') }])
);
}}>
<input type="text" name="text" />
<button type="submit">Add Todo</button>
</form>
withOverride((n: number
n) => n: number
n + 1)
);
} catch (var error: unknown
error) {
function showToast(message: string): void
showToast('Something went wrong!');
}
prerender
prerender
函数与 query
类似,不同之处在于它会在构建时调用以预渲染结果。用于每次重新部署最多更改一次的数据。
¥The prerender
function is similar to query
, except that it will be invoked at build time to prerender the result. Use this for data that changes at most once per redeployment.
import { function prerender<Output>(fn: () => MaybePromise<Output>, options?: {
inputs?: RemotePrerenderInputsGenerator<void>;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<void, Output> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
export const const getPosts: RemotePrerenderFunction<void, any[]>
getPosts = prerender<any[]>(fn: () => MaybePromise<any[]>, options?: {
inputs?: RemotePrerenderInputsGenerator<void>;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(async () => {
const const posts: any[]
posts = await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
SELECT title, slug
FROM post
ORDER BY published_at
DESC
`;
return const posts: any[]
posts;
});
你可以在动态页面上使用 prerender
函数,从而允许部分预渲染数据。这将带来非常快速的导航,因为预渲染数据可以与其他静态资源一起存储在 CDN 上。
¥You can use prerender
functions on pages that are otherwise dynamic, allowing for partial prerendering of your data. This results in very fast navigation, since prerendered data can live on a CDN along with your other static assets.
在浏览器中,预渲染的数据使用 Cache
API 保存。此缓存在页面重新加载后仍然存在,并在用户首次访问应用的新部署时被清除。
¥In the browser, prerendered data is saved using the Cache
API. This cache survives page reloads, and will be cleared when the user first visits a new deployment of your app.
当整个页面都包含
export const prerender = true
时,你无法使用查询,因为它们是动态的。
预渲染参数(Prerender arguments)
¥Prerender arguments
与查询一样,预渲染函数可以接受参数,该参数应为 validated 和 标准架构:
¥As with queries, prerender functions can accept an argument, which should be validated with a Standard Schema:
import * as import v
v from 'valibot';
import { function error(status: number, body: App.Error): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error } from '@sveltejs/kit';
import { function prerender<Output>(fn: () => MaybePromise<Output>, options?: {
inputs?: RemotePrerenderInputsGenerator<void>;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<void, Output> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender } from '$app/server';
import * as module "$lib/server/database"
db from '$lib/server/database';
export const const getPosts: RemotePrerenderFunction<void, void>
getPosts = prerender<void>(fn: () => MaybePromise<void>, options?: {
inputs?: RemotePrerenderInputsGenerator<void>;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(async () => { /* ... */ });
export const const getPost: RemotePrerenderFunction<string, any>
getPost = prerender<v.StringSchema<undefined>, any>(schema: v.StringSchema<undefined>, fn: (arg: string) => any, options?: {
inputs?: RemotePrerenderInputsGenerator<string> | undefined;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(), async (slug: string
slug) => {
const [const post: any
post] = await module "$lib/server/database"
db.function sql(strings: TemplateStringsArray, ...values: any[]): Promise<any[]>
sql`
SELECT * FROM post
WHERE slug = ${slug: string
slug}
`;
if (!const post: any
post) function error(status: number, body?: {
message: string;
} extends App.Error ? App.Error | string | undefined : never): never (+1 overload)
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you’re not catching the thrown error, which would prevent SvelteKit from handling it.
error(404, 'Not found');
return const post: any
post;
});
SvelteKit 爬虫在 预渲染页面 期间发现的任何对 getPost(...)
的调用都将自动保存,但你也可以使用 inputs
选项指定调用时应使用的值:
¥Any calls to getPost(...)
found by SvelteKit’s crawler while prerendering pages will be saved automatically, but you can also specify which values it should be called with using the inputs
option:
export const const getPost: RemotePrerenderFunction<string, void>
getPost = prerender<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>, options?: {
inputs?: RemotePrerenderInputsGenerator<string> | undefined;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(
import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(),
async (slug: string
slug) => { /* ... */ },
{
inputs?: RemotePrerenderInputsGenerator<string> | undefined
inputs: () => [
'first-post',
'second-post',
'third-post'
]
}
);
export const const getPost: RemotePrerenderFunction<string, void>
getPost = prerender<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>, options?: {
inputs?: RemotePrerenderInputsGenerator<string> | undefined;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(
import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(),
async (slug: string
slug) => { /* ... */ },
{
inputs?: RemotePrerenderInputsGenerator<string> | undefined
inputs: () => [
'first-post',
'second-post',
'third-post'
]
}
);
Svelte 尚不支持异步服务器端渲染,因此你很可能只是从浏览器调用远程函数,而不是在预渲染期间调用。因此,你目前需要使用
inputs
。我们正在积极解决这个问题。
默认情况下,预渲染函数不包含在服务器包中,这意味着你无法使用任何未预渲染的参数调用它们。你可以设置 dynamic: true
来更改此行为:
¥By default, prerender functions are excluded from your server bundle, which means that you cannot call them with any arguments that were not prerendered. You can set dynamic: true
to change this behaviour:
export const const getPost: RemotePrerenderFunction<string, void>
getPost = prerender<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>, options?: {
inputs?: RemotePrerenderInputsGenerator<string> | undefined;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(
import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(),
async (slug: string
slug) => { /* ... */ },
{
dynamic?: boolean | undefined
dynamic: true,
inputs?: RemotePrerenderInputsGenerator<string> | undefined
inputs: () => [
'first-post',
'second-post',
'third-post'
]
}
);
export const const getPost: RemotePrerenderFunction<string, void>
getPost = prerender<v.StringSchema<undefined>, void>(schema: v.StringSchema<undefined>, fn: (arg: string) => MaybePromise<void>, options?: {
inputs?: RemotePrerenderInputsGenerator<string> | undefined;
dynamic?: boolean;
} | undefined): RemotePrerenderFunction<...> (+2 overloads)
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a fetch
call.
See Remote functions for full documentation.
prerender(
import v
v.function string(): v.StringSchema<undefined> (+1 overload)
export string
Creates a string schema.
string(),
async (slug: string
slug) => { /* ... */ },
{
dynamic?: boolean | undefined
dynamic: true,
inputs?: RemotePrerenderInputsGenerator<string> | undefined
inputs: () => [
'first-post',
'second-post',
'third-post'
]
}
);
处理验证错误(Handling validation errors)
¥Handling validation errors
只要你没有向远程函数传递无效数据,传递给 command
、query
或 prerender
函数的参数验证失败只有两个原因:
¥As long as you’re not passing invalid data to your remote functions, there are only two reasons why the argument passed to a command
, query
or prerender
function would fail validation:
函数签名在部署期间发生了变化,并且一些用户目前使用的是旧版本的应用
¥the function signature changed between deployments, and some users are currently on an older version of your app
有人正试图通过使用恶意数据攻击你暴露的端点来攻击你的网站
¥someone is trying to attack your site by poking your exposed endpoints with bad data
在第二种情况下,我们不想给攻击者任何帮助,因此 SvelteKit 将生成通用的 400 错误请求 响应。你可以通过实现 handleValidationError
服务器钩子来控制消息,该钩子与 handleError
类似,必须返回 App.Error
(默认为 { message: string }
):
¥In the second case, we don’t want to give the attacker any help, so SvelteKit will generate a generic 400 Bad Request response. You can control the message by implementing the handleValidationError
server hook, which, like handleError
, must return an App.Error
(which defaults to { message: string }
):
/** @type {import('@sveltejs/kit').HandleValidationError} */
export function function handleValidationError({ event, issues }: {
event: any;
issues: any;
}): {
message: string;
}
handleValidationError({ event: any
event, issues: any
issues }) {
return {
message: string
message: 'Nice try, hacker!'
};
}
import type { import HandleValidationError
HandleValidationError } from '@sveltejs/kit';
export const const handleValidationError: HandleValidationError
handleValidationError: import HandleValidationError
HandleValidationError = ({ event: any
event, issues: any
issues }) => {
return {
message: string
message: 'Nice try, hacker!'
};
};
如果你知道自己在做什么,并且想要退出验证,可以传递字符串 'unchecked'
代替 schema:
¥If you know what you’re doing and want to opt out of validation, you can pass the string 'unchecked'
in place of a schema:
import { import query
query } from '$app/server';
export const const getStuff: any
getStuff = import query
query('unchecked', async ({ id: string
id }: { id: string
id: string }) => {
// the shape might not actually be what TypeScript thinks
// since bad actors might call this function with other arguments
});
form
不接受模式,因为你始终会传递一个FormData
对象。你可以根据需要自由地解析和验证它。
使用 getRequestEvent(Using getRequestEvent)
¥Using getRequestEvent
在 query
、form
和 command
函数中,你可以使用 getRequestEvent
函数获取当前的 RequestEvent
对象。这使得构建与 Cookie 交互的抽象变得容易,例如:
¥Inside query
, form
and command
you can use getRequestEvent
to get the current RequestEvent
object. This makes it easy to build abstractions for interacting with cookies, for example:
import { function getRequestEvent(): RequestEvent<Partial<Record<string, string>>, string | null>
Returns the current RequestEvent
. Can be used inside server hooks, server load
functions, actions, and endpoints (and functions called by them).
In environments without AsyncLocalStorage
, this must be called synchronously (i.e. not after an await
).
getRequestEvent, import query
query } from '$app/server';
import { import findUser
findUser } from '$lib/server/database';
export const const getProfile: any
getProfile = import query
query(async () => {
const const user: any
user = await function getUser(): any
getUser();
return {
name: any
name: const user: any
user.name,
avatar: any
avatar: const user: any
user.avatar
};
});
// this function could be called from multiple places
function function getUser(): any
getUser() {
const { const cookies: Cookies
Get or set cookies related to the current request
cookies, const locals: App.Locals
Contains custom data that was added to the request within the server handle hook
.
locals } = function getRequestEvent(): RequestEvent<Partial<Record<string, string>>, string | null>
Returns the current RequestEvent
. Can be used inside server hooks, server load
functions, actions, and endpoints (and functions called by them).
In environments without AsyncLocalStorage
, this must be called synchronously (i.e. not after an await
).
getRequestEvent();
const locals: App.Locals
Contains custom data that was added to the request within the server handle hook
.
locals.userPromise ??= import findUser
findUser(const cookies: Cookies
Get or set cookies related to the current request
cookies.Cookies.get: (name: string, opts?: CookieParseOptions) => string | undefined
Gets a cookie that was previously set with cookies.set
, or from the request headers.
get('session_id'));
return await const locals: App.Locals
Contains custom data that was added to the request within the server handle hook
.
locals.userPromise;
}
请注意,RequestEvent
的某些属性在远程函数内部有所不同。没有 params
或 route.id
,你无法设置标头(除了写入 Cookie,并且只能在 form
和 command
函数中设置),并且 url.pathname
始终是 /
(因为客户端实际请求的路径纯粹是实现细节)。
¥Note that some properties of RequestEvent
are different inside remote functions. There are no params
or route.id
, and you cannot set headers (other than writing cookies, and then only inside form
and command
functions), and url.pathname
is always /
(since the path that’s actually being requested by the client is purely an implementation detail).
重定向(Redirects)
¥Redirects
在 query
、form
和 prerender
函数中,可以使用 redirect(...)
函数。在 command
函数内部无法实现此功能,因为你应该避免在此处重定向。(如果确实需要,你可以返回一个 { redirect: location }
对象并在客户端中处理它。)
¥Inside query
, form
and prerender
functions it is possible to use the redirect(...)
function. It is not possible inside command
functions, as you should avoid redirecting here. (If you absolutely have to, you can return a { redirect: location }
object and deal with it in the client.)