用途:单例(singleton)是拥有固定 id、只能创建一次的文档,常见于站点设置、导航、页脚。该技能介绍如何用 Studio 一等公民 API 注册和呈现单例,并迁移旧实现。
配置:在 defineConfig 的 document.singletons 中登记,而非 schema 类型上。支持字符串简写(如 'siteSettings',展开为 id、documentId、schemaType 同名)与 defineSingleton({documentId, schemaType, title, initialValue}) 对象;多个单例可共享同一 schemaType。也可用解析函数 singletons: (prev, context) => [...]。配置解析时会校验 id、documentId、schemaType 与模板,失败聚合为 ConfigResolutionError。
Studio 自动行为:为每个单例生成带标签的初始值模板并从所有“新建”入口移除;向文档作用域配置注入 context.singleton;过滤 duplicate 动作;在默认 Structure 内容列表中把单例追加到文档类型列表之后。删除、取消发布、丢弃仍可用,作为“重置”手段;显式 structure 不会被过滤,也不会对“悬空”单例告警。
Structure 用法:默认结构无需额外代码;自定义 structure 需显式添加,辅助方法按定义 id 索引,未知 id 抛 SerializeError。可用 S.list().singletons([[ids]])、S.listItem().singleton(id)、S.document().singleton(id)、S.documentListItem().singleton(id)。注意 S.documentTypeListItems() 不含单例;S.list().singletons() 返回的 builder 无 .items(),需先 .items([...]);重复添加同一单例会抛重复 id 错误。
共享 schemaType:声明单例后该类型的普通模板被替换,类型从新建菜单消失。若仍需创建普通文档,需显式定义不带 singleton 标签的模板,并在结构中用 S.documentTypeListItem(typeName) 重新列出。
插件迁移:从 sanity-plugin-singleton-management(或 sanity-plugin-singleton-tools)迁移时,删除 options: {singleton: true}、singletonTools() 插件,改用注册表;结构辅助函数对应 S.listItem().singleton、S.list().singletons 与 S.documentTypeListItems()。插件默认 documentId 为 schema 类型名,字符串简写可保持现有内容 id 不变。插件原本只允许 publish、discardChanges、restore,如需保留更严格行为可自定义 document.actions。
限制:未提供第三方收费、价格与效果信息;平台、版本或使用前提等未在资料中说明的部分暂未提供。