服务端渲染

createSSRApp()

创建一个支持服务端渲染的应用实例。

类型定义

declare function createSSRApp(root: Component | View, config?: AppConfig): SSRApp

参数

参数	类型	说明
`root`	`Component` \| `View`	根组件或视图对象
`config`	`AppConfig`	可选的应用配置

返回值

类型	说明
`SSRApp`	SSR 应用实例

详情

使用方式与 createApp 一致，区别在于：

mount() 支持传入 SSRContext 进行激活
创建的应用实例支持客户端水合模式

参考：SSR 基础

renderToString()

将应用渲染为 HTML 字符串。

类型定义

declare function renderToString(root: SSRApp | View, context?: SSRContext): Promise<string>

参数

参数	类型	说明
`root`	`SSRApp \| View`	应用实例或视图
`context`	`SSRContext`	可选的 SSR 上下文

返回值

类型	说明
`Promise<string>`	渲染的 HTML 字符串

示例

import { createSSRApp, renderToString } from 'vitarx'
import { App } from './App'

const app = createSSRApp(App)
const html = await renderToString(app)

renderToStream()

流式渲染应用。

类型定义

declare function renderToStream(
  root: SSRApp | View,
  context: SSRContext,
  options: StreamingSink
): Promise<void>

参数

参数	类型	说明
`root`	`SSRApp \| View`	应用实例或视图
`context`	`SSRContext`	SSR 上下文
`options`	`StreamingSink`	流式接收器

示例

import { createSSRApp, renderToStream } from 'vitarx'

const app = createSSRApp(App)
const context = {}

await renderToStream(app, context, {
  push(chunk) {
    res.write(chunk)
  },
  close() {
    res.end()
  },
  error(err) {
    console.error(err)
  }
})

renderToReadableStream()

渲染为 Web ReadableStream。

类型定义

declare function renderToReadableStream(
  root: SSRApp | View,
  context?: SSRContext
): ReadableStream<string>

renderToNodeStream()

渲染为 Node.js ReadableStream。

类型定义

declare function renderToNodeStream(
  root: SSRApp | View,
  context?: SSRContext
): Promise<NodeJS.ReadableStream>

pipeToWritable()

将渲染结果管道到 Node.js WritableStream。

类型定义

declare function pipeToWritable(
  root: SSRApp | View,
  writable: NodeJS.WritableStream,
  context?: SSRContext
): Promise<void>

hydrate()

在客户端激活服务端渲染的 HTML。

类型定义

declare function hydrate(
  root: SSRApp | View,
  container: HostContainer | string,
  context?: SSRContext
): Promise<void>

参数

参数	类型	说明
`root`	`SSRApp \| View`	应用实例或视图
`container`	`HostContainer \| string`	容器元素或选择器
`context`	`SSRContext`	可选的 SSR 上下文

示例

import { createSSRApp, hydrate } from 'vitarx'
import { App } from './App'

const app = createSSRApp(App)
await hydrate(app, '#root')

参考：水合

isSSR()

判断当前是否在 SSR 环境中运行。

类型定义

declare function isSSR(): boolean

注意事项

不推荐使用此 API，它不支持摇树优化。推荐使用 __VITARX_SSR__ 编译时常量，打包工具可以在编译时将其替换为 true 或 false，从而实现死代码消除。

示例

// 不推荐
if (isSSR()) {
  // 服务端逻辑
}

// 推荐
if (__VITARX_SSR__) {
  // 服务端逻辑（打包时会被摇树优化）
}

isHydrating()

判断当前是否正在进行水合。

类型定义

declare function isHydrating(): boolean

useSSRContext()

获取当前 SSR 上下文。

类型定义

declare function useSSRContext<T = Record<string, any>>(): SSRContext<T> | null

返回值

类型	说明
`SSRContext<T>` \| `null`	SSR 上下文，不在 SSR 环境中返回 `null`

示例

tsx

import { useSSRContext } from 'vitarx'

function MyComponent() {
  const ctx = useSSRContext()
  if (ctx) {
    // 在 SSR 中可以访问上下文
    ctx.title = 'My Page'
  }
  return <div>Content</div>
}

参考：SSR 上下文

WARNING