Actions API 参考
添加于:
astro@4.15.0
Action 帮助你构建一个类型安全的后端,你可以从客户端代码和 HTML 表单中调用它。所有用于定义和调用 Action 的工具函数都由 astro:actions
模块暴露。有关示例和使用说明,请参阅 Actions 指南。
从 astro:actions
导入
段落标题 从 astro:actions 导入defineAction()
段落标题 defineAction()
添加于:
astro@4.15.0
defineAction()
函数接受一个 handler()
函数,其中包含在调用 Action 时要运行的服务器逻辑,以及一个可选的 input
属性,用于在运行时验证输入参数。
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
属性字段来确定要验证的对象:
isInputError()
段落标题 isInputError()类型:(error?: unknown | ActionError) => boolean
astro@4.15.0
isInputError()
函数常用于检查 ActionError
是否是输入验证错误。当 input
验证器是 z.object()
时,输入错误包括一个 fields
对象,其中错误消息按名称分组。
更多关于使用 isInputError()
的信息,请参见 表单输入错误指南。
ActionError
段落标题 ActionError
添加于:
astro@4.15.0
ActionError
构造函数常用于在 handler()
函数中抛出错误。它接受一个 code
属性,描述发生的错误(例如:"UNAUTHORIZED"
),以及一个可选的 message
属性,提供进一步的细节。
code
段落标题 code
添加于:
astro@4.15.0
code
属性接受所有 HTTP 状态码的人类可读版本。以下是支持的 code:
BAD_REQUEST
(400): 客户端发送了无效的输入。当 actioninput
验证器验证失败时会抛出此错误。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
添加于:
astro@4.15.0
message
属性接受一个字符串。(例如:“用户必须登录。“)