NNext.js 中文网 GitHub

draftMode

draftMode 函数的 API 参考。

draftMode 是一个异步函数,允许你启用和禁用草稿模式(Draft Mode),以及检查 Server Component 中是否启用了草稿模式。

app/page.ts
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
}
app/page.js
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
}

参考#

可用的方法和属性如下:

MethodDescription
isEnabled一个布尔值,指示是否启用了草稿模式。
enable()在 Route Handler 中通过设置 cookie(__prerender_bypass)来启用草稿模式。
disable()在 Route Handler 中通过删除 cookie 来禁用草稿模式。

小知识#

  • draftMode 是一个返回 Promise 的异步函数。你必须使用 async/await 或 React 的 use 函数。
    • 在 14 及更早版本中,draftMode 是一个同步函数。为了向后兼容,在 Next.js 15 中你仍然可以同步访问它,但此行为将来会被弃用。
  • 每次运行 next build 时都会生成一个新的绕过 cookie 值。这确保绕过 cookie 无法被猜到。
  • 要通过 HTTP 在本地测试草稿模式,你的浏览器需要允许第三方 cookie 和本地存储访问。
  • isEnabled 可以在缓存指令作用域内读取。其他运行时 API(如 cookies() 和 headers())不允许在缓存指令作用域内使用,即使草稿模式处于激活状态。
  • 在缓存指令作用域内调用 enable() 或 disable() 会抛出错误。
  • 启用草稿模式后,缓存指令作用域下的所有函数和组件都会在每次请求时重新执行,且结果不会保存到缓存中。这确保草稿内容始终是最新的。

示例#

启用草稿模式#

要启用草稿模式,创建一个新的 Route Handler 并调用 enable() 方法:

app/draft/route.ts
import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}
app/draft/route.js
import { draftMode } from 'next/headers'

export async function GET(request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}

禁用草稿模式#

默认情况下,草稿模式会话会在浏览器关闭时结束。

要手动禁用草稿模式,请在 Route Handler 中调用 disable() 方法:

app/draft/route.ts
import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.disable()
  return new Response('Draft mode is disabled')
}
app/draft/route.js
import { draftMode } from 'next/headers'

export async function GET(request) {
  const draft = await draftMode()
  draft.disable()
  return new Response('Draft mode is disabled')
}

然后,发送请求以调用该 Route Handler。如果使用 <Link> 组件 调用该路由,你必须传入 prefetch={false},以防止在预取时意外删除 cookie。

检查是否启用了草稿模式#

你可以在 Server Component 中使用 isEnabled 属性检查是否启用了草稿模式:

app/page.ts
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
  return (
    <main>
      <h1>My Blog Post</h1>
      <p>Draft Mode is currently {isEnabled ? 'Enabled' : 'Disabled'}</p>
    </main>
  )
}
app/page.js
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
  return (
    <main>
      <h1>My Blog Post</h1>
      <p>Draft Mode is currently {isEnabled ? 'Enabled' : 'Disabled'}</p>
    </main>
  )
}

版本历史#

VersionChanges
v15.0.0-RCdraftMode 现在是一个异步函数。可以使用 codemod。
v13.4.0引入 draftMode。
Next.js 中文网