From 9f8e8784cffca4cd3edcf5cf5c5d9774b80a8a94 Mon Sep 17 00:00:00 2001 From: Nin3 <30520689+Nin3lee@users.noreply.github.com> Date: Sun, 27 Oct 2024 11:00:59 +0800 Subject: [PATCH 1/6] i18n(zh-cn): add `astro-actions.mdx` --- .../zh-cn/reference/modules/astro-actions.mdx | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 src/content/docs/zh-cn/reference/modules/astro-actions.mdx diff --git a/src/content/docs/zh-cn/reference/modules/astro-actions.mdx b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx new file mode 100644 index 0000000000000..c63d414a2b101 --- /dev/null +++ b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx @@ -0,0 +1,173 @@ +--- +title: Actions API 参考 +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +

+ +Action 帮助你构建一个类型安全的后端，你可以从客户端代码和 HTML 表单中调用它。所有用于定义和调用 Action 的工具函数都由 `astro:actions` 模块暴露。有关示例和使用说明，请参阅 [Actions 指南](/zh-cn/guides/actions/)。 + +## 从 `astro:actions` 导入 + +```js +import { + actions, + defineAction, + isInputError, + ActionError, + } from 'astro:actions'; +``` + +### `defineAction()` + +`defineAction()` 函数接受一个 [`handler()`](#handler-属性) 函数，其中包含在调用 Action 时要运行的服务器逻辑，以及一个可选的 [`input`](#input-验证器) 属性，用于在运行时验证输入参数。 + +```ts +export const server = { + getGreeting: defineAction({ + input: z.object({ + name: z.string(), + }), + handler: async (input, context) => { + return `Hello, ${input.name}!` + } + }) +} +``` + +#### `handler()` 属性 + +

+ +**类型：**`(input, context) => any` +

+ +`defineAction()` 函数接受一个 `handler()` 函数，其中包含在调用 Action 时要运行的服务器逻辑。此函数可以返回数据，这些数据将自动序列化并发送给调用者。 + +`handler()` 函数被调用时，接受用户输入作为其第一个参数。如果设置了 [`input`](#input-验证器) 验证器，那么用户输入将在传递给 `handler()` 前进行验证。第二个参数是一个 `context` 对象，包含大多数 Astro 的 [标准端点上下文](#端点上下文)，不包括 `getActionResult()`, `callAction()`, 和 `redirect()`。 + +返回值使用 [devalue 库](https://github.com/Rich-Harris/devalue) 进行解析。它支持 JSON 值，以及 `Date()`, `Map()`, `Set()`, 或 `URL()` 的实例。 + +#### `input` 验证器 + +

+ +**类型：**`ZodType | undefined` +

+ +可选的 `input` 属性接受一个 Zod 验证器，用于在运行时验证处理程序的输入。如果 action 验证失败，将返回 [`BAD_REQUEST` 错误](#actionerror) 并跳过 `handler`。 + +如果省略 `input`，则 `handler` 将接收 JSON 请求的 `unknown` 类型的输入，以及表单请求的 `FormData` 类型。 + +##### 与 `accept: 'form'` 一起使用 + +如果你的 action 接受表单输入，请使用 `z.object()` 验证器将表单数据自动解析为类型化对象。表单数据字段支持以下验证器： + +- 使用 `z.number()` 验证类型为 `number` 的输入 +- 使用 `z.boolean()` 验证类型为 `checkbox` 的输入 +- 使用 `z.instanceof(File)` 验证类型为 `file` 的输入 +- 使用 `z.array(/* validator */)` 验证相同 `name` 的多个输入 +- 使用 `z.string()` 验证所有其他输入 + +`z.object()` 验证器还支持包括 `.refine()`, `.transform()`, 和 `.pipe()` 在内的扩展函数。 + +要搭配应用不同验证器的组合，请使用 `z.discriminatedUnion()` 包装器，它根据表单的特定字段以缩小类型范围。此示例通过接受表单提交以判断是 “创建(create)” 或是 “更新(update)” 了一名用户信息，判断时使用表单域的 `type` 属性字段来确定要验证的对象： + +```ts +import { defineAction } from 'astro:actions'; +import { z } from 'astro:schema'; + +export const server = { + changeUser: defineAction({ + accept: 'form', + input: z.discriminatedUnion('type', [ + z.object({ + // 当 `type` 字段中的值含有 `create` 时匹配 + type: z.literal('create'), + name: z.string(), + email: z.string().email(), + }), + z.object({ + // 当 `type` 字段中的值含有 `update` 时匹配 + type: z.literal('update'), + id: z.number(), + name: z.string(), + email: z.string().email(), + }), + ]), + async handler(input) { + if (input.type === 'create') { + // input 为 { type: 'create', name: string, email: string } + } else { + // input 为 { type: 'update', id: number, name: string, email: string } + } + }, + }), +}; +``` + +### `isInputError()` + +

+ +**类型：**(error?: unknown | ActionError) => boolean
+ +

+ +`isInputError()` 函数常用于检查 `ActionError` 是否是输入验证错误。当 `input` 验证器是 `z.object()` 时，输入错误包括一个 `fields` 对象，其中错误消息按名称分组。 + + +更多关于使用 `isInputError()` 的信息，请参见 [表单输入错误指南](/zh-cn/guides/actions/#展示表单输入错误)。 + + +### `ActionError` + +

+ +

+ +`ActionError` 构造函数常用于在 `handler()` 函数中抛出错误。它接受一个 `code` 属性，描述发生的错误（例如：`"UNAUTHORIZED"`），以及一个可选的 `message` 属性，提供进一步的细节。 + +#### `code` + +

+ +

+ +`code` 属性接受所有 HTTP 状态码的人类可读版本。以下是支持的 code： + +- `BAD_REQUEST` (400): 客户端发送了无效的输入。当 action `input` 验证器验证失败时会抛出此错误。 +- `UNAUTHORIZED` (401): 客户端缺乏有效的身份验证凭据。 +- `FORBIDDEN` (403): 客户端无权访问资源。 +- `NOT_FOUND` (404): 服务器找不到请求的资源。 +- `METHOD_NOT_SUPPORTED` (405): 服务器不支持请求的方法。 +- `TIMEOUT` (408): 服务器在处理请求时超时。 +- `CONFLICT` (409): 服务器无法更新资源，因为存在冲突。 +- `PRECONDITION_FAILED` (412): 服务器不满足请求的前提条件。 +- `PAYLOAD_TOO_LARGE` (413): 服务器无法处理请求，因为负载过大。 +- `UNSUPPORTED_MEDIA_TYPE` (415): 服务器不支持请求的媒体类型。注意：Actions 已经检查了 JSON 和表单请求的 [`Content-Type` 标头](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Type)，所以你可能不需要手动引发此代码。 +- `UNPROCESSABLE_CONTENT` (422): 服务器无法处理请求，因为存在语义错误。 +- `TOO_MANY_REQUESTS` (429): 服务器已超出指定的速率限制。 +- `CLIENT_CLOSED_REQUEST` (499): 客户端在服务器响应之前关闭了请求。 +- `INTERNAL_SERVER_ERROR` (500): 服务器意外失败。 +- `NOT_IMPLEMENTED` (501): 服务器不支持请求的功能。 +- `BAD_GATEWAY` (502): 服务器从上游服务器接收到无效响应。 +- `SERVICE_UNAVAILABLE` (503): 服务器暂时不可用。 +- `GATEWAY_TIMEOUT` (504): 服务器从上游服务器接收到超时。 + +#### `message` + +

+ +

+ +`message` 属性接受一个字符串。（例如："用户必须登录。"） + +[canonical]: https://en.wikipedia.org/wiki/Canonical_link_element From 218522d36bec9eba8b7d34724e5447facf7cc7f4 Mon Sep 17 00:00:00 2001 From: Nin3 <30520689+Nin3lee@users.noreply.github.com> Date: Sun, 27 Oct 2024 11:02:31 +0800 Subject: [PATCH 2/6] Update `astro-actions.mdx` --- src/content/docs/zh-cn/reference/modules/astro-actions.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/zh-cn/reference/modules/astro-actions.mdx b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx index c63d414a2b101..5f4952b3fa052 100644 --- a/src/content/docs/zh-cn/reference/modules/astro-actions.mdx +++ b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx @@ -27,6 +27,10 @@ import { ### `defineAction()` +

+ +

+ `defineAction()` 函数接受一个 [`handler()`](#handler-属性) 函数，其中包含在调用 Action 时要运行的服务器逻辑，以及一个可选的 [`input`](#input-验证器) 属性，用于在运行时验证输入参数。 ```ts From 1d52fa2b3f9b27310fa1914413724fe589099f1b Mon Sep 17 00:00:00 2001 From: Nin3 <30520689+Nin3lee@users.noreply.github.com> Date: Sun, 27 Oct 2024 11:05:07 +0800 Subject: [PATCH 3/6] Update astro-actions.mdx --- .../zh-cn/reference/modules/astro-actions.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/content/docs/zh-cn/reference/modules/astro-actions.mdx b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx index 5f4952b3fa052..cdb23027ad93f 100644 --- a/src/content/docs/zh-cn/reference/modules/astro-actions.mdx +++ b/src/content/docs/zh-cn/reference/modules/astro-actions.mdx @@ -46,6 +46,27 @@ export const server = { } ``` +### `defineAction()` + +

+ +

+ +`defineAction()` 函数接受一个 [`handler()`](#handler-属性) 函数，其中包含在调用 Action 时要运行的服务器逻辑，以及一个可选的 [`input`](#input-验证器) 属性，用于在运行时验证输入参数。 + +```ts +export const server = { + getGreeting: defineAction({ + input: z.object({ + name: z.string(), + }), + handler: async (input, context) => { + return `Hello, ${input.name}!` + } + }) +} +``` + #### `handler()` 属性

From 0d5f4e968d0b42afc50b4a851e6bbe8b4ac961e7 Mon Sep 17 00:00:00 2001 From: Nin3 <30520689+Nin3lee@users.noreply.github.com> Date: Sun, 27 Oct 2024 11:13:48 +0800 Subject: [PATCH 4/6] Update link in `actions.mdx` --- src/content/docs/zh-cn/guides/actions.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/zh-cn/guides/actions.mdx b/src/content/docs/zh-cn/guides/actions.mdx index 4e66bf8c4ab01..6ada5d6e79517 100644 --- a/src/content/docs/zh-cn/guides/actions.mdx +++ b/src/content/docs/zh-cn/guides/actions.mdx @@ -16,7 +16,7 @@ Astro Actions 允许你定义和调用具有类型安全性的后端函数。Act - 使用 [Zod](https://zod.dev/?id=primitives) 自动校验 JSON 和表单数据输入。 - 生成类型安全的函数，以便从客户端调用后端，甚至可以[从 HTML 表单操作](#从-html-表单操作调用-action)中调用。无需手动 `fetch()` 调用。 -- 使用 [`ActionError`](/zh-cn/reference/api-reference/#actionerror) 对象标准化后端错误。 +- 使用 [`ActionError`](/zh-cn/reference/modules/astro-actions/#actionerror) 对象标准化后端错误。 ## 基本用法 @@ -129,7 +129,7 @@ async () => { -有关 [`defineAction()`](/zh-cn/reference/api-reference/#defineaction) 及其属性的详细信息，请参阅完整的 Actions API 文档。 +有关 [`defineAction()`](/zh-cn/reference/modules/astro-actions/#defineaction) 及其属性的详细信息，请参阅完整的 Actions API 文档。 ## 组织 actions @@ -339,7 +339,7 @@ Actions 将解析提交的表单数据为一个对象，使用每个输入的 `n } ``` - 请参阅 [`input` 验证器](/zh-cn/reference/api-reference/#input-验证器) 查看所有可用的校验器 + 请参阅 [`input` 验证器](/zh-cn/reference/modules/astro-actions/#input-验证器) 查看所有可用的校验器 3. 添加一个 `