Sanity Studio 定时发布（Scheduled Publishing）：从文档编辑器到 Schedules 工具的全栈指南-北京尧图网络

Sanity Studio 定时发布Scheduled Publishing从文档编辑器到 Schedules 工具的全栈指南【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity导读本文以 Sanity Studio 仓库中packages/sanity/src/core/scheduled-publishing/模块含其 README.md为骨架系统讲解 Sanity Studio 内置的 Scheduled Publishing 定时发布能力如何在文档编辑器中为内容创建、编辑与立即执行发布时间如何使用独立的 Schedules 工具按状态与日期管理全部定时任务以及如何按内容类型精细控制 Schedule 文档动作与 Scheduled 徽章。文章同时结合该目录下的插件注册、API 调用、轮询缓存等源码实现帮助你理解其底层原理并可直接照抄配置落地到自己的 Studio 中。读完你将掌握定时发布的完整功能清单、零配置启用方式、日期格式与文档动作/徽章的定制方案以及定时任务与 dataset 之间数据关系的边界。Scheduled Publishing 是什么Scheduled Publishing 是 Sanity 为 Studio 提供的内容定时发布能力你可以把内容安排到未来的某个时间点自动发布publish或取消发布unpublish并集中管理所有即将到来与已完成/失败的发布时间——整个过程无需编写任何自定义任务custom tasks或 Serverless 函数。它基于 Sanity 的Scheduling API实现该 API 面向 Growth 或更高等级其历史名称scheduled-publishing已作为弃用别名处理以避免与用户自定义插件重名。版本提示从当前仓库源码可见该模块被标注为beta且带有“未来大版本将停止支持dropping support on a future major version”的弃用注释例如 ScheduleAction.tsx。Sanity 正以Content Releases / Scheduled Drafts作为其演进方向——当 Studio 启用了 Scheduled Drafts 时Schedules 工具顶部会显示引导横幅见 Tool.tsx。因此新项目应优先评估 Content Releases本文则聚焦讲解 Legacy Scheduled Publishing 的完整机制。核心功能清单在文档编辑器中创建与编辑定时任务直接在当前文档上创建、编辑定时发布时间实时查看该文档当前的定时状态以及潜在的校验问题文档存在定时任务时编辑器顶部会渲染一个Upcoming schedule 横幅由ScheduleBanner实现见 ScheduleBanner.tsx显示发布/取消发布时间本地时区并在文档存在校验错误时给出警告文案This document has validation errors that should be resolved before its publish date.定义于 constants.tsx。用独立的 Schedules 工具纵览全局按状态过滤全部定时任务或用左侧日历按日期浏览对单个任务执行编辑、删除、立即发布操作自动校验即将执行的定时任务提前暴露问题通过任务上的用户头像/作者信息快速识别是谁创建了这条定时任务。任意时区下预览时间点击 Time Zone按钮即可切换预览时区适合跨国团队协作或按目标区域卡点发布支持按城市、时区缩写或名称搜索快速定位时区选中的时区会自动保存在浏览器 localStorage 中下次打开依旧生效。快速开始零配置启用Scheduled Publishing默认内置在 Sanity Studio 中无需安装额外 npm 包。启动 Studio 后插件会自动完成三件事见 plugin/index.ts为所有文档 schema 类型追加一个Schedule文档动作document action按钮直接出现在文档操作栏位于默认 Publish 动作之后为所有文档 schema 类型追加一个Scheduled文档徽章document badge实时显示该文档是否有即将执行的定时任务及具体时间在导航栏注册一个标题为Schedules的独立工具TOOL_TITLE Schedules见 constants.tsx工具图标为日历图标路由支持/state/:state与/date/:date两种子路由。在 resolveDocumentActions 中可以看到更精细的注入逻辑当文档为published版本versionType 为 published时不会注入 Schedule 动作否则会在现有publish动作之后插入 Schedule 动作若文档动作列表中没有publish动作则把 Schedule 动作放到列表最前面。文档徽章的注入则更简单直接在现有徽章列表末尾追加ScheduledBadge见 documentBadges/scheduled/index.ts。定制输入日期格式创建/编辑定时任务时日期输入框的显示格式默认是dd/MM/yyyy HH:mm。可以通过 workspace 配置中的scheduledPublishing.inputDateTimeFormat覆盖为任意合法的date-fnsformat token 字符串defineConfig({ ...yourConfig, scheduledPublishing: { enabled: true, // 例如 12/25/2000 6:30 AM自定义格式时务必包含分钟和小时。 inputDateTimeFormat: MM/dd/yyyy h:mm a, }, })默认值dd/MM/yyyy HH:mm同时定义在配置类型与默认插件解析处见 types.ts 与 resolveDefaultPlugins.ts。ScheduledPublishingPluginOptions还包含一个hidden的__internal__workspaceEnabled布尔字段用于标记当前 workspace 是否由 Sanity 在配置中默认启用了该能力。按内容类型定制 Schedule 文档动作插件默认把 Schedule 动作挂到所有文档类型上因此如果你的 Studio 已经自定义过文档动作document actions就需要主动从不需要它的类型上移除。下面示例只让movie类型显示 Schedule 按钮import {scheduledPublishing, ScheduleAction} from sanity/scheduled-publishing export default defineConfig({ // ... plugins: [scheduledPublishing()], document: { actions: (previousActions, {schemaType}) { /* * 请注意这只会改变按钮在 Studio 中的可见性。 * 拥有文档发布publish权限的用户仍可通过 Scheduled Publishing API * 直接创建定时任务。 */ if (schemaType.name ! movie) { // 从所有非 movie 类型中移除 schedule 动作 return previousActions.filter((action) action ! ScheduleAction) } return previousActions }, }, })关于ScheduleAction的实现有几点值得注意见 ScheduleAction.tsx权限控制动作内部通过useDocumentPairPermissions检查当前用户的publish权限无权限时按钮显示为 disabled并展示InsufficientPermissionsMessage提示ScheduleAction.tsx可用性判定按钮在以下场景被禁用——定时任务数据加载中、文档尚不存在既无 draft 也无 published 版本、该内容类型启用了 Live Edit保存即自动发布无需定时、或当前处于变体variant视角下Legacy 定时发布不支持变体否则会静默调度基础文档见 ScheduleAction.tsx计划升级提示当项目计划不支持 Scheduled Publishing 时点击按钮会弹出 upsell 对话框而非创建表单对话框内容文档已有定时任务时展示任务列表Schedules否则展示创建表单EditScheduleForm表单的 “Schedule” 按钮在未选择日期时禁用。按内容类型定制 Scheduled 文档徽章徽章与动作同理插件默认给所有文档类型加了Scheduled徽章不需要的类型应主动移除。下面示例只保留movie类型的徽章import {scheduledPublishing, ScheduledBadge} from sanity/scheduled-publishing export default defineConfig({ // ... plugins: [scheduledPublishing()], document: { actions: (previousBadges, {schemaType}) { if (schemaType.name ! movie) { // 从所有非 movie 类型中移除 scheduled 徽章 return previousBadges.filter((badge) badge ! ScheduledBadge) } return previousBadges }, }, })徽章的渲染逻辑见 ScheduledBadge.tsx会轮询当前文档的scheduled状态定时任务取最近一条schedules?.[0]如果存在有效的executeAt与action就渲染为Scheduled徽章悬停提示显示“Publishing on 时间 (local time)”或“Unpublishing on 时间 (local time)”。动作与徽章颜色的映射关系集中在 constants.tsxpublish动作使用 primary/positive 绿色调unpublish动作使用 danger/critical 红色调。深入源码底层数据模型与 APISchedule 数据模型定时任务的核心类型定义在 types.tsScheduleActionpublish | unpublish——定时发布或定时取消发布ScheduleStatescheduled | succeeded | cancelled——分别对应“Upcoming / Completed / Failed”三种状态状态标题映射见 constants.tsxScheduleSort可按createdAt或executeAt排序Schedule对象包含author、action、createdAt、dataset、documents[].documentId、executeAt、state、stateReason等字段。API 端点所有读写操作都通过useScheduleApi封装见 useScheduleApi.ts使用apiVersion: 2022-09-01的 Sanity client端点形如/schedules/{projectId}/{dataset}操作方法端点说明创建POST/schedules/{projectId}/{dataset}body 为{documents: [{documentId}], executeAt, name}executeAt会先被取整到最近的整秒setSeconds(0)、setMilliseconds(0)删除DELETE/schedules/{projectId}/{dataset}/{scheduleId}单条删除批量删除DELETE× N同上内部用Promise.allSettled并发执行立即发布POST/schedules/{projectId}/{dataset}/{scheduleId}/publish返回{transactionId}更新PATCH/schedules/{projectId}/{dataset}/{scheduleId}body 为PartialSchedule返回{transactionId}轮询与缓存刷新工具、文档动作、徽章和横幅都通过usePollSchedules获取数据见 usePollSchedules.ts。它基于 SWR默认模式default mode下每10 秒refreshInterval: 10000自动重新校验一次数据upsell 模式下不轮询禁用revalidateOnFocus、revalidateOnReconnectshouldRetryOnError为 false通过window自定义事件ScheduleEvents.delete / deleteMultiple / publish / update实现即时本地缓存更新例如删除定时任务后SWR 缓存立即过滤掉该条目并触发后台重新校验用户无需等待下一次轮询返回的 schedules 默认按执行时间排序executedAt || executeAt见 sortByExecuteDate.ts。文档编辑器的横幅注入Schedules 工具与文档横幅还借助form.components.input与studio.components.layout两个扩展点注入 UI见 plugin/index.tsDocumentBannerInput会向上追溯 schema 类型的根类型仅对document类型包装渲染ScheduledDocumentInput见 inputResolver.tsx后者把表单校验标记validation markers传给ScheduleBanner从而在存在定时任务时显示横幅。Schedules 工具的内部结构工具界面由 Tool.tsx 实现采用左右双栏布局左栏ToolCalendar日历支持按日期过滤日期 slug 使用yyyy-MM-dd格式并 sticky 固定右栏顶部分别是ScheduleFilters状态过滤器Upcoming / Completed / Failed顺序定义于SCHEDULE_FILTERS与TimeZoneButton时区切换、SchedulesContextMenu上下文菜单下方是Schedules虚拟滚动列表VirtualList。路由状态直接驱动界面router.state.state决定当前过滤状态router.state.date决定选中的日期未选择任何过滤时自动回退到第一个过滤器useFallbackNavigation。FAQ常见问题与边界行为Schedules 与 dataset 是什么关系Schedules 是独立于 dataset 的独特资源它与你 Sanity 项目及 dataset 关联但并不存放在 dataset 内部由 Scheduling API 托管插件只是替你调用该 API。理解这一点非常重要因为由此派生出以下行为由于定时任务不在 dataset 内无法通过 GROQ 或 GraphQL 查询它们删除 dataset 会立即删除其下所有定时任务删除 project 会立即删除所有定时任务sanity dataset export不会导出定时任务sanity dataset import也不支持导入服务端 dataset 复制server-side copy不包含定时任务当项目被禁用或封禁时所有定时发布必然失败因为此时不允许对 dataset 执行 mutation。时区数据来自哪里时区及其对应的城市、区域与夏令时偏移数据直接来自 vvo/dztb 库该库会自动同步 geonames.org 的数据。带校验错误的文档会定时发布吗会。即便文档存在校验错误validation errors到点后仍会照常发布。这条规则同样适用于你在工具中手动选择“立即发布”的定时任务。Studio 只会通过横幅、工具中的验证列表SchedulesValidation、ValidationList见 components/validation提前提示风险但不会阻止执行。补充说明启用条件scheduledPublishing.enabled: true与__internal__workspaceEnabled共同决定功能可用性当计划不支持时插件会进入 upsell 模式展示订阅升级提示而不是报错相关文案Forbidden. Please check that your project has access to Scheduled Publishing.见 constants.tsx。权限创建/编辑/删除定时任务依赖用户的文档publish权限即便按钮被自定义配置隐藏具备权限的用户仍可通过 Scheduling API 直接创建定时任务因此按钮可见性不等于能力隔离。监控机制工具会为每条任务渲染StateReasonFailedInfo失败原因、DateWithTooltip带时区提示的时间、作者信息User等便于追踪定时任务的执行情况与失败归因。至此你已经掌握了 Scheduled Publishing 从启用、定制到源码原理的完整链路默认三件套文档动作、文档徽章、Schedules 工具、日期格式定制、按类型移除动作/徽章、底层 API 端点与轮询刷新机制以及它与 dataset 的边界关系。接下来可以直接在 Studio 配置中按需裁剪或进一步阅读本文引用的源码文件深入了解实现细节。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Sanity Studio 定时发布（Scheduled Publishing）：从文档编辑器到 Schedules 工具的全栈指南

相关推荐

AR-NAR混合Transformer模型YuE2实战部署指南

(全新整理)上市公司-AI漂洗指数2010-2024年

WordPress Gutenberg 中 MenuGroup 组件解析：@wordpress/components 的菜单分组、可访问性与分隔线实现

更多资讯

gogcli 读取 Google Sheets 数据源表（Connected Sheets Extract）：`gog sheets datasource table read` 实战指南

累亏超9亿、营收增速骤降，加特兰冲刺科创板，能否解决“增长从哪来”难题？

SolidWorks模板配置指南：零件/装配体/工程图模板与自定义属性

1300 张 H200 完胜 10 万张芯片！Periodic Neon 开辟 AI 变强新路径

软件项目文档管理实战：需求、设计、测试、验收四类文档这样写

编码器停产EOL替代实战：选型、参数对标与PLC适配

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？