Sanity Studio 类型系统演进实录sanity/types 包 v3.86 → v6.13 变更全解读【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanitysanity/types是 Sanity Studio 生态中类型定义的核心包它承载了 Sanity 公共数据结构的全部 TypeScript 类型——从 schema 定义、验证规则、引用关系到用户、搜索、媒体库与 Portable Text。本文以该包在仓库中的 CHANGELOG.md 为骨架逐版本梳理 v3.86.0 至 v6.13.0 之间的所有重要特性、修复与破坏性变更并结合 packages/sanity/types/src 下的源码实现做纵深验证。读完本文你将掌握这套类型系统近年来的演进脉络、各版本升级时需要注意的兼容性红线以及如何在实际 schema 与验证开发中运用这些新能力。一、包定位与版本演进总览sanity/types在 package.json 中的定位是Type definitions for common Sanity data structures即面向所有常见 Sanity 数据结构的类型定义。它依赖sanity/client与sanity/media-library-types并约定 Node.js 版本不低于 22.12engines: {node: 22.12}浏览器兼容基线为 baseline 2024。从 CHANGELOG.md 可以看到该包的版本号跟随 Sanity 主仓库整体发布节奏绝大多数版本仅标注为Version bump only for package sanity/types纯版本号同步、无类型层面的实质变更真正有意义的变更集中在以下几个阶段版本区间主题重心v3.86 ~ v3.99图片 hotspot 配置、媒体库集成、PTE 单行模式、datetime 时区v4.0 ~ v4.22破坏性变更React 版本基线、引用透视、decorator 类型修正v5.0 ~ v5.31搜索策略、类型守卫、schema helper 保留、条件多 schema 引用v6.0 ~ v6.13破坏性变更Node 版本基线、headless 验证、验证标记稳定 code、用户属性类型仓库根目录的 ARCHITECTURE.md 与 CORE_CONCEPTS.md 可作为理解该包在整体架构中位置的补充阅读材料。二、两次破坏性变更版本基线红线CHANGELOG 中明确标注了两条⚠ BREAKING CHANGES这是升级时必须首先检查的红线1. v5.0.0放弃对 React 19.2 的支持v5.0.02025-12-16以 PR #11383 移除了对 React 19.2 以下版本的支持。这意味着如果你的 Studio 应用仍锁定在 React 18 或 React 19.0/19.1需要先将 React 升级到 19.2 及以上才能平滑升级到sanity/typesv5 系列。2. v6.0.0放弃对 Node.js 20 的支持v6.0.02026-06-11以 PR #12859 移除了对 Node 20 的支持并同步将 Studio 的默认搜索策略切换为groq2024详见下文第五节。升级到 v6 前请确认 CI 与本地开发环境的 Node.js 版本为 22 或更高——这与当前仓库中 package.json 声明的node 22.12引擎约束完全一致。三、Schema 定义与类型系统的持续打磨1.defineField内的类型自动补全保留v5.20.0v5.20.0 修复了 preserve type autocomplete for defineField inside defineType#12576。在此之前在defineType内部使用defineField时字段的选项与验证方法自动补全可能丢失修复后嵌套书写 schema 时 TypeScript 仍能精确推导出字段类型。该能力建立在 define.ts 与 defineTypes.ts 提供的defineField、defineType、defineArrayMember与typed四个入口之上仓库 defineReturnTypes.test.ts 和 typeMerge.test.ts 给出了返回类型合并行为的测试佐证。2. 保留用户传入的 schema helper 属性v6.9.0v6.9.0 的 preserve supplied schema helper properties#13237修复了 schema 定义中由用户提供的 helper 属性在类型推导时被吞掉的问题。这对于依赖在定义中附带自定义元数据如components、options扩展字段的插件开发者尤为重要。3.BlockRule的值类型修正v5.22.0v5.22.0 将BlockRule的 value 类型从any[]修正为PortableTextBlock#12509。这一点可直接在 block.ts 中得到验证export interface BlockRule extends RuleDefBlockRule, PortableTextBlock {}这意味着对 block 数组字段书写自定义验证时回调参数已经具备 Portable Text 块的完整类型约束而不再是无约束的any[]。4. 新增isArrayOfStringsSchemaType类型守卫v5.17.0v5.17.0 为 schema 断言族新增了isArrayOfStringsSchemaType守卫。在 asserters.ts 中可以看到其实现思路是数组且所有成员均为字符串 schema 类型export function isArrayOfStringsSchemaType(type: unknown): type is ArraySchemaTypestring { return isArraySchemaType(type) type.of.every((memberType) isStringSchemaType(memberType)) }同一文件还提供了isArrayOfBlocksSchemaType、isArrayOfObjectsSchemaType、isArrayOfPrimitivesSchemaType等姊妹守卫全部以jsonType与成员类型判定为基础形成一套完备的运行时类型收窄工具。这些断言函数从 index.ts 统一导出属于包的公共 API。5. 移除strike/strike-throughdecorator 混淆v4.6.0v4.6.0 的 removestrike/strike-throughdecorator confusion#10416厘清了 Portable Text decorator 的命名歧义。官方约定的 decorator 值为strike-through这一点在 block.ts 的默认 decorator 示例中有明确体现marks: { decorators: [ {title: Strong, value: strong}, {title: Emphasis, value: em}, {title: Underline, value: underline}, {title: Strike, value: strike-through}, {title: Code, value: code}, ] }6. 条件属性回调上下文补充pathv5.8.0v5.8.0 为ConditionalPropertyCallbackContext增加了path字段#11947。这让hidden、readOnly等条件属性回调ConditionalPropertyCallback定义于 types.ts能够感知字段在文档中的完整路径从而写出基于路径位置的动态显隐/只读逻辑。7.defineAssetAspect媒体库宽高比定义的强类型助手v4.12.0 引入v4.12.0 的 allow setting aspect definition to public#10900将媒体库 aspect 定义开放为公共 API配套提供了defineAssetAspect辅助函数与MediaLibraryAssetAspectDefinition类型见 defineAssetAspect.ts 与 types.ts。仓库 defineAssetAspect.test.ts 覆盖了宽高比定义的多种合法形态可作为编写自定义 aspect 时的类型参考。四、验证Validation系统的连续升级验证相关的改动是 CHANGELOG 中占比最重的部分几乎每个大版本都有针对性增强1. headless document validation 包与稳定标记 codev6.12.0v6.12.0 一次引入两项验证基础设施headless document validation 包#14093将文档验证能力从 Studio UI 中解耦允许在无头headless环境直接对文档执行验证stable codes to validation markers#14137为验证标记marker引入稳定 code使下游系统如诊断面板、CI 检查可以按 code 而非文案匹配错误避免因文案变更导致的回归。2. 取消支持与能力感知结果v6.13.0v6.13.0 在验证层面新增两处能力cancellation support#14307长文档的验证过程支持取消避免在编辑器快速输入时堆积无意义的验证任务capability-aware results#14306验证结果可感知宿主环境能力输出更贴合实际运行环境的判定结果。3. 上下文感知的验证规则解析v6.9.1v6.9.1 修复了 resolve context-aware validation rules in inputs#13878确保输入组件中依据上下文如当前值、兄弟字段动态生成的验证规则能够被正确解析执行。ValidationContext及相关类型定义在 validation/types.ts 中。4.hidden进入验证上下文v5.9.0v5.9.0 的 add hidden to validation context#12050将字段的hidden状态传入验证上下文。隐藏字段是否需要跳过验证、如何处理隐藏状态与必填规则的关系从此有了官方的上下文依据。5. 可控制undefined/null的排序行为v5.17.0v5.17.0 的 add ability to control undefined/null sorting#12367为 schema 排序配置增加了对undefined/null值排序位置的控制能力相关类型可见于 types.ts 中的SortOrdering与SortOrderingItem。6.assetRequired规则与媒体库选择的兼容v4.19.0v4.19.0 修复了 skip assetRequired rule to allow selection in media library#11197当通过媒体库而非直接上传选择资源时assetRequired规则不应误拦截。该规则定义于 image.tsexport interface ImageRule extends RuleDefImageRule, ImageValue { assetRequired(): ImageRule }典型用法为defineField({ name: cover, type: image, validation: (Rule) Rule.required().assetRequired(), })五、搜索策略与用户类型1.groq2024成为默认搜索策略v6.0.0v6.0.0 在移除 Node 20 支持的同时将 Studio 的搜索默认策略切换为groq2024。搜索策略在源码中被建模为可枚举常量见 search/types.tsexport const searchStrategies [groq2024, groqLegacy] as const export type SearchStrategy (typeof searchStrategies)[number]配套的isSearchStrategy守卫与SearchConfiguration字段级搜索权重配置见 common.ts共同构成了从 Studio 全局到单字段粒度的搜索能力配置体系。2.CurrentUser增加组织级用户属性v6.4.0v6.4.0 的 add user attribute types to CurrentUser#13395为CurrentUser引入了attributes字段。完整定义见 user/types.tsexport type UserAttributeType | string | string-array | integer | integer-array | number | number-array | boolean export type CurrentUserAttribute { [T in UserAttributeType]: {key: string; type: T; value: UserAttributeValueByType[T]} }[UserAttributeType] export interface CurrentUser { // ... /** Organization-scoped user attributes for the current project. */ attributes?: CurrentUserAttribute[] }该特性使得权限插件与个性化逻辑可以直接读取按组织划分的用户属性string、integer、number、boolean 及其数组形态而不再依赖非结构化的自定义字段。六、引用Reference体系的增强引用类型在近年经历了多轮重要演进1. 条件多 schema 引用v5.11.0v5.11.0 的 conditional multi schema references#12066允许引用字段根据条件动态匹配多个目标 schema突破了传统to数组的静态声明模式。相关类型ReferenceDefinition、ReferenceOptions、ReferenceTo定义于 reference.ts。2. 显示 incoming referencesv5.8.0v5.8.0 的 display incoming references#10761支持在文档视图中展示指向当前文档的引用列表其类型基础来自 reference/types.ts 中的ReferenceFilterOptions与过滤器解析器ReferenceFilterResolver体系。这为内容关系洞察inspect 面板提供了数据结构支撑。3. perspective stack 传入自定义引用过滤器v4.16.0v4.16.0 的 pass perspective stack to custom reference filters#11127让自定义引用过滤函数可以感知当前的 perspective 栈草稿/发布/版本叠加态并允许过滤函数返回期望的 perspective。对在多版本releases环境下开发引用过滤器的团队这是一个重要的行为升级。七、媒体库Media Library与资产能力扩展媒体库是 v3.99 ~ v5.3 阶段的高频演进主题v3.99.0Media Library 视频集成#9909媒体库从图片扩展至视频资产v3.94.0core 媒体验证器#9648为媒体资产提供统一验证v4.12.0aspect 定义开放为公共 API#10900配套defineAssetAspect类型助手v5.3.0thumbhash 支持用于媒体库预览占位 允许从媒体库选择私有资产#11756v4.8.0修复上传已存在于媒体库中的资产时的重复处理#10495v4.2.0媒体库字段级 GROQ 过滤器#9900可在字段层面约束可选择的媒体资产v5.22.0为 Media Library 插件引入持久化 key#12670。在 schema 类型层面image.ts 定义了ImageOptions.metadata支持blurhash、thumbhash、lqip、palette、exif等元数据类型与hotspot配置。其中 hotspot 配置化能力源自 v3.86.0 的 add image schema options for hotspot tool configuration#9185支持传入previews数组HotspotPreviewtitleaspectRatio用于在裁剪工具中呈现不同宽高比下的预览效果。八、Portable Text 编辑器与日期时间输入1. 单行 Portable Text 编辑器选项v3.93.0v3.93.0 的 add one line portable text editor option#9625为 block 类型新增options.oneLine将富文本编辑器限制为单行输入。源码定义见 block.tsexport interface BlockOptions extends BaseSchemaTypeOptions { spellCheck?: boolean unstable_whitespaceOnPasteMode?: preserve | normalize | remove /** 开启后编辑器限制所有换行与软换行粘贴多行内容会被归一化为单行。默认 false。 */ oneLine?: boolean }对于标题、副标题、口号等天然单行的富文本场景oneLine: true可以避免用户意外输入多行内容。2. PTE 插件可配置化v3.92.0v3.92.0 的 allow configuring PTE plugins#8785将 Portable Text 编辑器的插件列表开放为 schema 可配置项为编辑器能力的按需裁剪铺平了道路。3. datetime 输入增加时区设置v3.92.0v3.92.0 的 add timeZone settings to datetime input#8181为 datetime 字段引入了时区配置。对应类型见 datetime.tsexport interface DatetimeOptions extends BaseSchemaTypeOptions { dateFormat?: string timeFormat?: string timeStep?: number displayTimeZone?: string allowTimeZoneSwitch?: boolean }其中displayTimeZone指定展示时区、allowTimeZoneSwitch允许编辑者在输入界面切换时区对跨国内容团队意义重大。datetime 字段的min/max验证规则同样在 datetime.ts 中按 ISO 8601 格式约束。4. geopoint 字段的折叠选项v6.1.0v6.1.0 修复了 allow collapsible and collapsed options on geopoint fields#13109使地理位置字段支持collapsible/collapsed选项与 object 字段的折叠行为保持一致。九、文档系统、变体与其他能力1. 文档_system与版本感知v6.2.0v6.2.0 的 add document_systemto useDocumentVersions#13094让版本工具可以获取文档的系统元数据DocumentSystem定义于 documents/types.ts。同版本的修复确保temporarilyBuildDocumentSystem在空值场景下返回undefined而非错误值#13121避免边界情况下出现脏数据。2. 变体文档编辑v6.6.0v6.6.0 的 enable editing variant documents through the document form#13505允许在文档表单中直接编辑变体variant文档v6.9.0 进一步支持从已发布变体的兄弟节点创建草稿变体#13741。这依赖 documents/types.ts 中的StrictVersionLayeringOptions等版本分层类型。3. 表单与组件增强v5.8.0image 字段新增disableNew选项#12004禁用从表单新建图片而仅允许选择已有资产v5.6.0renderMembers函数加入 objects 与 fieldsets#11205支持细粒度自定义字段渲染同时新增资产的 Open in Source 能力#11826v5.3.0media-library 的 thumbhash 支持#76cda08v5.15.0升级到新的sanity/cli#12200。4. 依赖与工程化维护CHANGELOG 中还有大量依赖更新类修复sanity/client、sanity/insert-menu、react-is19 升级、sanity/media-library-types等它们保证了类型包与客户端、插入菜单等周边包的语义一致。v3.94.0 的 stop publishing src folders to npm#9744则是一次发布物精简减小了 npm 包体积。十、升级路径与实战建议综合以上演进升级sanity/types时建议按以下顺序排查先查版本红线v5 起要求 React ≥ 19.2v6 起要求 Node.js ≥ 22与 package.json 的 engines 声明一致先升级运行时环境再升级依赖关注验证行为变化v6.12 引入的稳定 code 与 v6.13 的取消/能力感知结果可能影响依赖验证 marker 文案的下游系统建议迁移到 code 匹配利用新增类型能力block 验证回调现在拥有PortableTextBlock类型v5.22.0defineField内嵌写法v5.20.0与 schema helper 属性保留v6.9.0让 schema 代码更类型安全适配引用与搜索变化多 schema 条件引用v5.11.0、引用过滤器感知 perspectivev4.16.0与默认groq2024搜索策略v6.0.0是行为级变化涉及自定义引用过滤器或搜索排序的团队需重点回归媒体库使用者关注 aspect 公共化v4.12.0、私有资产选择v5.3.0与assetRequired兼容修复v4.19.0的叠加效果。对于希望深入类型定义细节的读者可直接阅读 src/index.ts 的完整导出清单、schema/definition 下各内建类型的定义文件以及 test 目录下的类型测试如 defineReturnTypes.test.ts、options.test-d.ts这些是理解每个类型行为边界的一手材料。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考