事件对象 Event Object

事件对象携带传入的请求和上下文。

每次收到新的 HTTP 请求时，h3 都会在内部创建一个 Event 对象并将其传递给事件处理程序，直到发送响应。

事件会传递到所有生命周期钩子和可组合实用程序，以将其用作上下文。

示例：

js
import { defineEventHandler, getQuery, readBody } from 'h3'

app.use(defineEventHandler(async (event) => {
  // 记录事件。`.toString()` 字符串化为简单字符串，如 `[GET] /<path>`
  console.log(`Request: ${event.toString()}`)

  // 解析查询参数
  const query = getQuery(event)

  // 尝试读取请求主体
  const body = await readBody(event).catch(() => {})

  // 将请求作为响应回显
  return {
    path: event.path,
    method: event.method,
    query,
    body,
  }
}))

属性

事件的主要属性包括：

event.node

允许您访问本机 Node.js 请求和响应。在 Node.js/Bun 以外的运行时中，h3 使用 unjs/unenv 制作兼容的垫片。

!IMPORTANT 尽量避免依赖 event.node.* 上下文，而应优先使用 h3 实用程序。

js
defineEventHandler((event) => {
  event.node.req // Node.js HTTP Request
  event.node.res // Node.js HTTP Response
})

event.web?

如果可用，则使用具有 request 和 url 属性的对象来访问本机 Web 请求上下文。

event.method

访问规范化（大写）请求 method。

event.path

访问请求路径。（示例： /test?test=123）

  • context 包含有关请求的一些上下文信息。
  • headers 包含请求标头的 规范化版本。
  • handled 包含布尔值，指示请求是否已终止。

event.headers

访问规范化的请求 Headers。

!TIP 您也可以使用 getHeaders(event) 或 getHeader(event, name) 来简化界面。

event.context

上下文是一个包含有关请求的任意信息的对象。 您可以将自定义属性存储在event.context中，以便在可组合实用程序之间共享。

###event.handled

指定响应是否已处理。最初对于每个请求，它都是false，当生成响应时，它设置为true。

**高级：**如果您手动处理响应，请将其设置为true以告诉h3停止发送任何响应。

##方法

h3提供了一个函数来帮助您在请求结束之前创建响应。

###event.respondWith

respondWith方法用于在不结束请求的情况下创建响应。

您必须使用Response构造函数制作响应。

!TIP 最佳实践是显式 return 而不是 respondWith。

!IMPORTANTrespondWith 调用始终优先于当前和下一个事件处理程序的返回值。如果没有返回值，请求将继续，直到堆栈运行器结束。

示例：

js
defineEventHandler(async (event) => {
  await event.respondWith(new Response('Hello World'))
  return '...' // 不起作用
})

app.use(
  defineEventHandler(async (event) => {
    await event.respondWith(new Response('Hello World'))
    return '...' // 不起作用
  }),
)

通过此示例，客户端将收到“Hello World”。