React Spectrum UXP 集成设计同一份源码同时运行在浏览器与 UXP 插件环境的组件替换方案【免费下载链接】react-spectrumA collection of libraries and tools that help you build adaptive, accessible, and robust user experiences.项目地址: https://gitcode.com/GitHub_Trending/re/react-spectrum本文基于 React Spectrum 仓库中的 RFC 文档 rfcs/2021-v3-uxp-integration.md2021-02-22 提出作者 Kris Nye完整解析其核心设计如何在一个 monorepo 内为 UXPUnified Extensibility Platform统一扩展平台提供环境特定的 React 组件覆盖让消费者用同一份业务源码同时构建现代浏览器与 UXP 插件含 Adobe XD 等产品的插件环境两个目标。读完后你可以理解“命名空间 同名替换 重导出”这一环境适配模式的具体组织方式、构建期/运行期选择机制、对消费者与开发流程的影响以及它在当前仓库中的落地形态。背景为什么需要环境特定的组件实现UXP 是 Adobe 的统一扩展平台既用于 Adobe 内部项目也用于面向 Adobe 产品包括 XD的公开插件。与标准 Web 环境不同UXP 使用自己的渲染栈部分组件的底层 DOM/渲染表现与浏览器不同。这一点在其他 RFC 中也有呼应rfcs/2019-v3-architecture.md 在阐述 v3 三层架构react-stately平台无关的状态、react-aria主题无关的行为、react-spectrum带主题的外观时明确把 UXP 列为动机之一新平台希望复用 react-spectrum 的跨平台代码同时提供自己的平台特定渲染rfcs/2019-v3-dom-props.md 也指出UXP 有时会用不同的元素渲染同样的组件跨平台共享代码时对 DOM props 和className的约束必须更刻意。本 RFC 要解决的问题因此非常具体提供一组符合 React Spectrum 规范的组件使其运行在 UXP 上最终用户应能用同一份源码构建既跑在现代浏览器、又跑在 UXP 上的应用且可能只需要少量打包配置来支持 UXP 特定组件的构建期选择。总体组织react-spectrum-uxp命名空间RFC 的核心方案是为 UXP 专用模块开辟一个独立的 npm 命名空间在 npmjs.com 上新建react-spectrum-uxp组织作为所有 UXP 特定 react-spectrum 模块的命名空间UXP 实现与它所替换的 react-spectrum 模块同名但托管在新命名空间下。例如react-spectrum/button的 UXP 版本位于react-spectrum-uxp/button每个模块在 monorepo 内对应一个新项目位于packages/react-spectrum-uxp/[name]。这个目录布局与仓库现有的 workspace 声明是天然兼容的根目录 package.json 的workspaces字段使用通配符packages/*/*因此任何新增的packages/react-spectrum-uxp/*子包都会自动纳入 Yarn workspaces 管理不需要修改根配置。每个 UXP 模块的实现约定RFC 为每一个需要 UXP 定制实现的react-spectrum模块规定了一致的工程约定在packages/react-spectrum-uxp/[name]创建对应的新项目实现 UXP 兼容版本的相关组件导出 API 与packages/react-spectrum/[name]完全一致相同的导出名、相同的类型对不需要修改的组件直接从packages/react-spectrum/[name]重导出re-export运行在 UXP 上时按需导出 UXP 特定组件运行在 Web 上时重导出基础实现可以通过 package.json 的条件导出conditional exports在打包期确定正确入口否则在运行期判断。值得注意的是仓库里已经存在这种“薄重导出包”的真实先例。以 packages/react-spectrum/button/src/index.ts 为例react-spectrum/button的全部源码就是一个 re-export 文件把Button、ActionButton、ToggleButton等组件及其 Props 类型从adobe/react-spectrum的细粒度导出中转出来。RFC 设想的 UXP 包正是同一模式的推广包壳负责“按环境路由”无需实现的部分全部委托给基础包从而保证 API 同步、避免重复类型系统与构建流程。同时模块的exports字段本身就是条件分发的落点。参考 packages/react-spectrum/button/package.json其exports声明了source/types/import/require等不同条件下的入口UXP 入口可以按同样的条件导出机制接入打包器的解析流程。面向消费者的单一入口adobe/react-spectrum-uxp单包RFC 还规划了一个消费者级别的聚合包新建packages/adobe/react-spectrum-uxp包API 与导出和packages/adobe/react-spectrum相同对需要定制的组件导出 UXP 特定实现对无需改动的组件直接重导出基础实现发布为 npm 上的adobe/react-spectrum-uxp。这保证了消费者不需要关心内部有多少个模块被替换——只需要替换一个顶层导入。作为对照当前的主聚合包是 packages/adobe/react-spectrum/package.json其main指向./dist/exports/index.cjs说明仓库已有完整的 exports 打包产物体系可供新包参照。开发者体验UXP 版 StorybookUXP 开发者需要一种便捷的、带热模块替换HMR的组件开发与测试手段。RFC 提议在packages/react-spectrum-uxp/storybook增加一个 UXP 兼容的 Storybook 插件包该包复用各模块既有的./stories文件仓库中确实普遍存在例如 packages/adobe/react-spectrum/stories、packages/react-aria/stories、packages/react-aria-components/stories避免为 UXP 单独维护一套 story构建出的插件可以在三处查看Web 浏览器、UXP 演示应用、类 XD 的插件环境为所有客户端提供 HMR标记为 private不发布到 npm。这与仓库现有的 Storybook 工作流一致根 package.json 中已有start、build:storybook等基于 Storybook Parcel 的脚本UXP 插件可寄生在同一套 stories 资产之上。消费方式改导入或用打包器 aliasUXP 客户端的消费路径被设计得非常轻最简方式把现有adobe/react-spectrum的导入改成adobe/react-spectrum-uxp更优方式在大多数打包器中使用alias让源码零改动地指向 UXP 入口。RFC 也留了一个开放选项如果条件导出无法覆盖场景可能需要为 Parcel 和 webpack 各提供一个简化消费的插件但从源码结构看条件导出很可能使这些插件变得不必要这一判断在 RFC 的“Open Questions”中同样是待验证项。开发与协作流程为避免给核心 react-spectrum 维护者增加负担RFC 规定了治理边界代码所有权code ownerspackages/react-spectrum-uxp目录与packages/adobe/react-spectrum-uxp单包目录划给 UXP 团队的架构师负责CI 保障现有的 PR 测试流程会确保 UXP 特定构建目标始终成功隔离性UXP 目录内的任何变更不应影响现有浏览器模块破坏性变更的处理react-spectrum 模块 API 的不兼容变更可能导致对应 UXP 项目编译出错此时核心开发者修复类型错误并把 UXP 团队成员加入评审即可。这一机制的前提是仓库的 API 检查体系根 package.json 提供check-apis、build:api-branch、compare:apis等脚本用于对比分支与origin/main的公开 API 差异可以及时发现波及 UXP 包的破坏性改动。代价、兼容性分析与被否决的替代方案代价Drawbacks新增 UXP 模块会增加仓库复杂度与构建时间没有 UXP 环境的贡献者无法测试影响 UXP 的变更。向后兼容性不改动任何现有公开 API 与入口点Web 消费者的行为零变化UXP 用户需要借助条件导出或 parcel/webpack 配置指向新的 UXP 入口。RFC 明确对比了两个被否决的替代方案这段权衡对做类似多平台适配的仓库很有参考价值替代方案优点缺点被否决原因用独立外部仓库作为 UXP 入口不依赖 react-spectrum 团队的流程UXP API 与标准 API 难以保持同步重复类型系统与构建流程收益很小贡献者无法在仓库内积累 react-spectrum 经验核心贡献者无法通过类型系统在本地发现 UXP 依赖被破坏在运行期集成 UXP 组件消费者无需任何打包配置UXP 代码会被打进所有 bundle无论是否消费 UXP 都增加体积即仓库内命名空间 构建期/入口选择是最终方案以少量构建复杂度换取 API 一致性、类型级联检查与体积最小化。RFC 中还附带了一个基础 Storybook 与 UXP Button 的样例实现以仓库分支对比compare链接的形式给出作为该方案的最小可行验证原文指向main与作者分支的对比此处不输出外部链接读者可在 RFC 原文中查看。开放问题与当前仓库中的实现状态RFC 保留的开放问题包括Parcel 如何为 UXP 配置打包Webpack 如何配置需要 UXP 环境的测试如何加入package.json 条件导出能否真正处理 UXP 与 Web 入口的选择需要如实说明的是在当前仓库快照中packages/react-spectrum-uxp与packages/adobe/react-spectrum-uxp目录尚未出现——全仓库对 “uxp” 的引用集中在 RFC 文档本身本文档以及 rfcs/2019-v3-architecture.md、rfcs/2019-v3-dom-props.md。因此本文将该 RFC 作为一份完整的设计文档来解读它给出的命名空间、模块约定、单包入口、Storybook 插件与治理规则是可复用的工程蓝图且仓库现有的重导出式薄包如react-spectrum/button、条件导出字段与packages/*/*工作区通配都已为按此蓝图落地做好了结构性准备。小结这篇 RFC 的价值在于为“同一份源码、多种运行环境”提供了一个克制且工程化的模式用独立 npm 命名空间react-spectrum-uxp承载环境特定组件模块同名、API 同构不需要的组件一律重导出基础实现把“环境差异”收敛到尽可能少的组件上通过 package.json 条件导出或运行期判断完成入口选择消费者只需改一行导入或配置一个打包 alias用 code owners 与隔离目录保证 UXP 演进不拖累核心仓库用类型系统让破坏性变更在编译期互相可见明确否决了“外部仓库”与“全量运行期集成”两条路线理由分别是 API 同步成本与 bundle 体积。对需要在 Web 与插件/桌面环境之间维护同一组件库的团队这套“命名空间隔离 重导出兜底 构建期入口选择”的组合是一个可直接迁移的参考架构。【免费下载链接】react-spectrumA collection of libraries and tools that help you build adaptive, accessible, and robust user experiences.项目地址: https://gitcode.com/GitHub_Trending/re/react-spectrum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
