Actions API 参考

Added in: astro@4.15.0

Action 帮助你构建一个类型安全的后端，你可以从客户端代码和 HTML 表单中调用它。所有用于定义和调用 Action 的工具函数都由 astro:actions 模块暴露。有关示例和使用说明，请参阅 Actions 指南。

从 astro:actions 导入

段落标题 从 astro:actions 导入

import {
  actions,
  defineAction,
  isInputError,
  isActionError,
  ActionError,
 } from 'astro:actions';

defineAction()

段落标题 defineAction()

Added in: astro@4.15.0

defineAction() 函数接受一个 handler() 函数，其中包含在调用 Action 时要运行的服务器逻辑，以及一个可选的 input 属性，用于在运行时验证输入参数。

export const server = {
    getGreeting: defineAction({
    input: z.object({
      name: z.string(),
    }),
    handler: async (input, context) => {
      return `Hello, ${input.name}!`
    }
  })
}

handler() 属性

段落标题 handler() 属性

类型：(input, context) => any

defineAction() 函数接受一个 handler() 函数，其中包含在调用 Action 时要运行的服务器逻辑。此函数可以返回数据，这些数据将自动序列化并发送给调用者。

handler() 函数被调用时，接受用户输入作为其第一个参数。如果设置了 input 验证器，那么用户输入将在传递给 handler() 前进行验证。第二个参数是一个 context 对象，包含大多数 Astro 的 标准端点上下文，不包括 getActionResult(), callAction(), 和 redirect()。

返回值使用 devalue 库 进行解析。它支持 JSON 值，以及 Date(), Map(), Set(), 或 URL() 的实例。

input 验证器

段落标题 input 验证器

类型：ZodType | undefined

可选的 input 属性接受一个 Zod 验证器，用于在运行时验证处理程序的输入。如果 action 验证失败，将返回 BAD_REQUEST 错误 并跳过 handler。

如果省略 input，则 handler 将接收 JSON 请求的 unknown 类型的输入，以及表单请求的 FormData 类型。

与 accept: 'form' 一起使用

段落标题 与 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 属性字段来确定要验证的对象：

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()

段落标题 isInputError()

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

Added in: astro@4.15.0

isInputError() 函数常用于检查 ActionError 是否是输入验证错误。当 input 验证器是 z.object() 时，输入错误包括一个 fields 对象，其中错误消息按名称分组。

更多关于使用 isInputError() 的信息，请参见 表单输入错误指南。

isActionError()

段落标题 isActionError()

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

Added in: astro@4.15.0

isActionError() 工具函数用于检查你的 action 是否引发了 handler 属性 中的 ActionError。这在缩小 try / catch 块中的泛型错误的类型时很有用。

ActionError

段落标题 ActionError

Added in: astro@4.15.0

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

code

段落标题 code

Added in: astro@4.15.0

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 标头，所以你可能不需要手动引发此代码。
• 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

Added in: astro@4.15.0

message 属性接受一个字符串。（例如：“用户必须登录。“）