Payload 如何配置草稿自动保存Autosave并只手动发布【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload在 Payload 中管理内容时常见的诉求是编辑器在后台持续改动文档改动自动以草稿形式保存、随时不丢但对外的“线上版本”只有在你显式点击发布后才更新。本文基于 Payload 仓库自带文档Autosave、Drafts、Versions说明如何完成这条路径开启 Versions Drafts Autosave让编辑过程按固定间隔自动存为草稿并用访问控制保证只有已发布内容对外可见发布动作只能由人手动触发。适用前提来自 Installation任一 JavaScript 包管理器pnpm、npm 或 yarn 2pnpm 优先不支持 yarn 1.xNode.js24.15.0、Next.js16.2.6、TypeScript6.0.3任一兼容数据库MongoDB、Postgres 或 SQLite及对应 Database Adapter。新建项目可直接运行npx create-payload-app并按提示操作在已有 Next.js 应用中集成则按安装文档安装payload、payloadcms/next和数据库适配器。下文以仓库中的空白模板为例其集合定义位于src/collections/目录如 TagsPayload 配置入口是payload.config.tsConfig Overview。开启 Drafts 并启用 Autosave文档明确说明Autosave 依赖 Versions 和 Drafts 同时启用才能工作。而 Versions 虽然默认开启但 Drafts 默认是关闭的Versions Overview 指出 versions 默认启用、maxPerDoc: 100、drafts 禁用。因此你不能只开 autosave必须在集合或 Global 配置里显式写出versions.drafts再在其中开启autosave。以模板里的Tags集合为对象在 Tags.ts 中补充versions配置import type { CollectionConfig } from payload export const Tags: CollectionConfig { slug: tags, admin: { useAsTitle: name, }, fields: [ { name: name, type: text, required: true, }, ], versions: { drafts: { autosave: true, }, }, }autosave可以传true也可以传对象来定制两个属性Autosave 文档选项说明interval自动保存的防抖间隔毫秒。文档更新在此间隔上被 debounced默认800。showSaveDraftButton设为true后即使开启了 autosave 也显示 Save as draft 按钮。默认false。需要自定义时的写法取自文档示例versions: { drafts: { autosave: { interval: 1500, // 自动保存间隔毫秒 showSaveDraftButton: true, }, }, }Collections 和 Globals 支持完全相同的 autosave 配置项。只让已发布内容对外可见开启 Drafts 后Payload 会向 schema自动注入一个_status字段用于标记文档是draft还是publishedDrafts 文档。Admin UI 会把文档显示为三种状态之一Draft—— 从未发布过只存在草稿版本Published—— 已发布且没有更新的草稿Changed—— 已发布但存在尚未发布的更新草稿。这里有一个容易踩的边界draft参数本身不会把_status: draft的文档从 API 结果里挡掉。未登录用户能否看到草稿必须靠read访问控制来约束Access Control。典型写法是登录用户可读全部文档未登录用户只能读_status为published的文档import type { CollectionConfig } from payload export const Tags: CollectionConfig { slug: tags, access: { read: ({ req }) { // If there is a user logged in, // let them retrieve all documents if (req.user) return true // If there is no user, // restrict the documents that are returned // to only those where _status is equal to published return { _status: { equals: published, }, } }, }, versions: { drafts: { autosave: true, }, }, }文档同时提醒了一个真实限制如果你的集合里已有存量文档在开启草稿功能之前创建的这些文档在重新保存之前不会有_status字段。对这类集合访问控制需要同时放行_status为published与_status不存在的文档read: ({ req }) { if (req.user) return true return { or: [ { _status: { equals: published, }, }, { _status: { exists: false, }, }, ], } }手动发布只有显式设置_status: published才上线Autosave 不会触碰已发布的线上文档——它只是把编辑进度存成新的草稿版本发布完全由你决定。文档给出的规则是发布必须显式地把_status: published写进 data反过来把_status设为draft即“取消发布”。Admin UI 侧的行为Drafts 文档开启 Drafts 后原来的 Save 按钮会被替换为“保存草稿”与“发布”操作已发布文档的侧边栏顶部会出现 unpublish 按钮把当前发布文档退回草稿状态已发布后又存了草稿时会出现 revert to published 按钮用于丢弃草稿改动、回到已发布状态草稿版本仍保留只是新增一条反映最后发布状态的版本。如果希望通过角色限制谁能发布可在update访问控制中返回针对_status的查询约束当约束阻止发布时Admin UI 会自动隐藏 Publish 和 Unpublish 按钮例如管理员return true编辑只能更新_status为draft的文档。API 侧draft参数与_status的组合行为以 Drafts 文档的 Quick reference 表 为准与“只手动发布”最相关的几行是操作draft参数data 中的_status结果Updatetrue省略或draft只更新 versions 表主集合文档不变Updatetruepublished主集合被更新为_status: published覆盖行为Updatefalse或省略published主集合被更新为_status: published即带draft: true的 update 只会写 versions 表线上主文档保持不变——这正是 autosave 生效时的写入方式。验证配置是否生效按文档描述可以从三处确认1. Admin UI 的自动保存指示器。开启 Autosave 后文档被修改时草稿会自动创建Admin UI 在侧边栏右上角增加一个指示器说明文档最后一次保存的时间。编辑后观察该指示器是否随时间推进即可判断 autosave 在按interval工作。2. 版本存储位置与形态。启用 versions 后数据库会按slug自动创建版本集合命名模式为_slug_versions例如tags_versions见 Versions Overview。每条版本记录包含parent父文档 ID、完整的文档数据副本以及一个autosave元属性用于标记该版本是否由自动保存产生文档示例中的版本数据节选{ _id: 61cf752c19cdf1b1af7b61f1, parent: 61ce1354091d5b3ffc20ea6e, autosave: false, version: { // your documents data goes here }, createdAt: 2021-12-31T21:25:00.99200:00, updatedAt: 2021-12-31T21:25:00.99200:00 }注意存储策略Autosave不会每次防抖触发都新建一条版本而是只创建一条autosave 版本、之后每次自动保存都更新这一条。文档给出的理由是 autosave 约按 800ms 间隔触发逐次建版本会迅速把_versions集合刷满。3. 读取行为对照。文档明确了验证读结果的方式普通find/findByID不带draft参数返回主集合中的已发布文档忽略草稿版本传入draft: true时返回 versions 表中最近的一条版本草稿或已发布均可能。REST 形式来自 Drafts 文档// REST API写入草稿 POST /api/tags?drafttrue // Local API await payload.create({ collection: tags, data: { // your data here }, draft: true, })查看版本历史还可以走 Versions 文档列出的 REST 端点例如集合的GET /api/{collectionSlug}/versions分页查询版本、GET /api/{collectionSlug}/versions/:id、POST /api/{collectionSlug}/versions/:id恢复某个版本Local API 对应payload.findVersions/findVersionByID/restoreVersion。限制与已知边界前置依赖不可省略Autosave 依赖 Versions 和 Drafts 启用Drafts 依赖 Versions 启用。Versions 虽默认开启maxPerDoc: 100可用0保存全部版本但 drafts 默认关闭必须显式配置versions.drafts。draft: true不绕过必填校验要保存不完整文档靠的是draft: true放宽必填字段而不是设置_status: draft。存量文档开启草稿前已存在的文档在重新保存前没有_status访问控制需按上文示例兼容这种情况。定时发布是独立开关versions.drafts.schedulePublish需要应用具备处理 Jobs 的机制才能执行定时任务与本文的“手动发布”目标无关不需要时不要启用。配置完成后编辑流即为Admin UI 编辑文档 → 每interval默认 800ms防抖后自动写入单一 autosave 草稿版本、侧边栏显示最后保存时间 → 普通 API 读取始终只返回已发布内容 → 由人显式发布_status: published或 UI 的 Publish 按钮后线上版本才更新。【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考