实时预览

通过 Live Preview 功能，你可以直接在 Admin Panel 中渲染你的前端应用。当你输入时，更改会实时生效，无需保存草稿或发布修改。该功能在 Server-side 和 Client-side 环境下均可使用。

Live Preview 的工作原理是在页面上渲染一个 iframe 来加载你的前端应用。Admin Panel 通过 window.postMessage 事件与你的应用通信。每当文档发生更改时，这些事件就会被触发。你的应用监听这些事件，并使用接收到的数据重新渲染自身。

要添加 Live Preview 功能，请在 Payload Config 中使用 admin.livePreview 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    // ...
    // highlight-start
    livePreview: {
      url: 'http://localhost:3000',
      collections: ['pages'],
    },
    // highlight-end
  },
})

提醒： 你也可以在单独的 Collection Admin Configs 和 Global Admin Configs 中定义 admin.livePreview 属性。此处定义的设置将作为覆盖项合并到顶层配置中。

选项

设置 Live Preview 非常简单。可以通过 Root Admin Config 全局配置，也可以在单独的 Collection Admin Configs 和 Global Admin Configs 中进行配置。配置完成后，启用的文档顶部会出现一个新的 "Live Preview" 标签页。点击该标签页将打开预览窗口并加载你的前端应用。

以下是可用的选项：

Path描述
url *字符串或返回字符串的函数，指向你的前端应用。该值用作 iframe 的 src。更多详情。
breakpoints用作预览窗口中"设备尺寸"的断点数组。每个项目都会在工具栏中显示为一个选项。更多详情。
collections启用 Live Preview 的 collection slug 数组。
globals启用 Live Preview 的 global slug 数组。

* 星号表示该属性为必填项。

URL

url 属性解析为指向你前端应用的字符串。该值会被用作渲染你前端的 iframe 的 src 属性。一旦加载完成，Admin Panel 将通过 window.postMessage 事件直接与你的应用通信。

要设置 URL，请在你的 Payload Config 中使用 admin.livePreview.url 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    // ...
    livePreview: {
      url: 'http://localhost:3000', // highlight-line
      collections: ['pages'],
    },
  },
})

动态 URL

你也可以传递一个函数来动态格式化 URL。这对于多租户应用、本地化或任何需要基于正在编辑的文档生成 URL 的场景非常有用。

要设置动态 URL，可以在你的 Payload 配置 中将 admin.livePreview.url 属性设置为一个函数：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    // ...
    livePreview: {
      // highlight-start
      url: ({
        data,
        collectionConfig,
        locale
      }) => `${data.tenant.url}${ // 多租户顶级域名
        collectionConfig.slug === 'posts' ? `/posts/${data.slug}` : `${data.slug !== 'home' : `/${data.slug}` : ''}`
      }${locale ? `?locale=${locale?.code}` : ''}`, // 本地化查询参数
      collections: ['pages'],
    },
    // highlight-end
  }
})

url 函数会接收以下参数：

路径描述
data正在编辑的文档数据。这包括尚未保存的更改。
locale当前正在编辑的语言环境（如适用）。更多详情。
collectionConfig正在编辑的文档的 Collection Admin 配置。更多详情。
globalConfig正在编辑的文档的 Global Admin 配置。更多详情。
reqPayload 请求对象。

你可以从这个函数返回绝对 URL 或相对 URL。如果你在构建时不知道前端 URL，可以返回相对 URL，在这种情况下，Payload 会通过从浏览器窗口注入协议、域名和端口来自动构建绝对 URL。返回相对 URL 对于像 Vercel 这样的平台很有帮助，因为你可能有在构建时未知的预览部署 URL。

如果你的应用需要完全限定的 URL，或者你尝试在不同域的前端进行预览，可以使用 req 属性来构建这个 URL：

url: ({ data, req }) => `${req.protocol}//${req.host}/${data.slug}` // highlight-line

断点设置

breakpoints 属性是一个对象数组，用作预览窗口中的"设备尺寸"。每个项目都会在工具栏中呈现为一个选项。当选择某个断点时，预览窗口将调整到该断点指定的精确尺寸。

要设置断点，请在 Payload Config 中使用 admin.livePreview.breakpoints 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    // ...
    livePreview: {
      url: 'http://localhost:3000',
      // highlight-start
      breakpoints: [
        {
          label: '移动设备',
          name: 'mobile',
          width: 375,
          height: 667,
        },
      ],
      // highlight-end
    },
  },
})

每个断点可配置以下选项：

PathDescription
label *下拉菜单中显示的标签。用户将看到这个名称。
name *断点的名称。
width *断点的宽度。用于设置 iframe 的宽度。
height *断点的高度。用于设置 iframe 的高度。

* 星号表示该属性为必填项。

"Responsive"（响应式）选项始终存在于下拉菜单中，无需额外配置。这是初始加载时使用的默认断点。该选项将 iframe 的宽度和高度设置为 100%，使其以最大尺寸填充屏幕，并随着窗口尺寸变化自动调整。

你也可以通过工具栏中的相应输入框显式调整 Live Preview 的尺寸。这将临时将断点选择覆盖为"Custom"（自定义），直到再次选择预定义的断点。

如果希望不使用断点自由调整 Live Preview 尺寸，可以点击工具栏中的按钮在新窗口中打开。这将关闭 iframe 并打开一个可自由调整尺寸的新窗口。关闭新窗口后，iframe 会自动重新打开。

示例

要查看实际演示，请参考官方的 Live Preview 示例。