工程前置条件

接入前必读

工程前置条件

MBJIA Tools 同时包含基础 UI 和模板加强业务组件。基础 UI 可以按普通 React 组件接入；素材、上传、AI、权益等模块需要业务接口、登录态、权限、事件协议和浏览器能力。

React 17Ant Design 4Less / CSS ModulesSharedWorker

接入建议： 如果只是使用按钮、弹窗、输入框、分页等基础能力，优先接入 @mbjia/ui。如果要使用素材、上传、AI、支付权益等业务能力，请先完成本页检查项。

何时需要阅读本页

基础 UI

确认 React、AntD 和样式编译即可。

低风险

业务组件

需要接口、权限、事件协议和业务上下文。

需联调

上传能力

依赖 SharedWorker、BroadcastChannel 和上传接口。

强依赖

AntD 文档通常先给出组件定位和使用边界，再展开示例与 API。这里也按这个思路处理：先判断你的接入目标，再检查对应依赖。

版本要求

项目	推荐版本	是否必需	说明
React	~17.0.0	是	当前源码按 React 17 开发和验证。React 18 项目需要单独验证。
React DOM	~17.0.0	是	建议与 React 保持一致，避免弹层、浮层、worker 回调出现差异。
Ant Design	4.24.16	是	基础 UI 多数继承 AntD 4 能力。AntD 5 项目不建议直接接入。

{
  "react": "~17.0.0",
  "react-dom": "~17.0.0",
  "antd": "4.24.16"
}

样式要求

组件源码里同时存在 Less、CSS Modules、styled-components 和 AntD 样式。业务项目的构建工具必须能处理这些样式，否则会出现样式丢失、类名异常或弹层错位。

能力	用途	缺失影响
Less	业务组件和部分基础组件样式	组件样式无法编译
CSS Modules	多个组件依赖模块化 class	className 映射异常
styled-components	部分编辑器、展示和业务组件	运行时样式缺失
AntD 样式	继承 AntD 4 组件能力	弹窗、按钮、输入框等基础样式异常

主题色

@mbjia/components 会设置 AntD 全局主题色 #171436。当前文档站主色使用业务指定渐变，仅用于文档视觉，不代表组件运行时主题已经同步修改。

浏览器能力

上传相关能力需要浏览器支持 worker 和跨页面通信能力。普通基础 UI 不依赖这些能力。

能力	影响模块	说明
SharedWorker	@mbjia/upload-manager、EveryWhereUpload	多页面共享上传队列和上传状态
BroadcastChannel	上传事件同步	跨页面传递上传事件和进度
File API	上传、素材导入	读取用户选择的图片、视频、文件
Worker URL	上传 worker 构建	生产环境需要正确提供 worker 文件路径

如果目标浏览器不支持 SharedWorker，上传管理器会输出错误，素材上传流程可能不可用。混剪生产环境还会读取 process.env.sharedWorkerPath。

业务上下文

模块	代表组件	依赖项
素材管理	AssetManagementModal、AssetModal	素材接口、分类、搜索、分页、用户素材、批量选择协议
全局上传	EveryWhereUpload、AssetUpload	上传 worker、素材归属、上传事件、失败重试
AI 搜索	AiSearch、InputTextAndTags	搜索接口、标签输入、素材选择、页面状态
支付权益	Payment、VipModal、BuyPointsModal	用户权益、订单、积分、支付接口
视频处理	MediaSplittingFlow、VideoCaptureFlow	视频分析接口、任务轮询、权益校验

接入前检查

检查项	要求
包源	项目能访问 http://verdaccio.atvideo.cc，并正确配置 @mbjia scope。
登录态	业务组件所在页面能读取模板加登录 Cookie、token 或用户信息。
接口权限	素材、权益、AI、上传、支付等接口已经对当前业务开通。
环境域名	通过 @mbjia/site-env 或业务侧配置得到正确的后端域名和站点环境。
事件协议	下载、上传、素材选择、权益不足等流程要按文档监听和派发事件。
样式构建	业务项目能处理 Less、CSS Modules、styled-components 和 AntD 样式。

如果项目不满足这些条件，优先只接入 @mbjia/ui，不要直接接入素材、上传、AI、支付等强业务模块。