快速开始

Get Started

3 分钟跑通第一个组件

这页只保留上手必需步骤：配置私有源、安装包、引入组件。能跑起来以后，再按需要查看业务组件、API 和数据结构。

安装与私库如何使用文档按场景接入完整文档地图工程前置条件选择包版本与准确性

只想先用一个组件？

先装 @mbjia/ui，复制下面的 Button 示例即可。业务组件可以稍后再接。

npm install @mbjia/ui

接入流程

确认工程环境

React 建议为 17，AntD 为 4.24.x，构建工具需要支持 Less、CSS Modules、styled-components。

配置私有 npm 源

为 @mbjia scope 指向内部 Verdaccio，并确认本地或内网能解析私库域名。

安装需要的包

只用按钮、弹窗、输入框时安装 @mbjia/ui；接素材、上传、AI、权益时再安装业务包。

按模块阅读 API

每个核心模块都提供使用示例、Props、事件、数据结构和注意事项。

不熟悉时先看哪里

如果不知道组件名，不建议从分类里逐个打开。先按任务走：

目标	入口
第一次看，不知道怎么查	如何使用文档
不确定该用哪个包	选择合适的包
知道业务目标但不知道组件名	按场景接入
知道组件名或关键词	使用右上角站内搜索
要查 Props、事件、数据结构	完整文档地图
关心历史版本和说明准确性	版本与准确性

1. 配置私有源

在业务项目根目录创建或更新 .npmrc：

@mbjia:registry=http://verdaccio.atvideo.cc
registry=https://registry.npmmirror.com/

本地还需要能解析私库域名。公司内网环境通常已经配置；如果没有，需要在 hosts 中加入：

47.103.41.64 verdaccio.atvideo.cc

2. 安装包

基础 UI

适合按钮、弹窗、输入框、分页等普通页面组件。

推荐先接

业务组件

适合素材管理、上传、AI 搜索、支付权益、视频处理等模板加业务流程。

需要联调

Hooks / Utils

适合复用状态、异步、DOM、业务工具函数和接口辅助逻辑。

npm install @mbjia/ui

需要业务组件、Hooks 或工具函数时再安装：

npm install @mbjia/components
npm install @mbjia/hooks @mbjia/utils

3. 引入第一个组件

import { Button } from '@mbjia/ui'

export default function Demo() {
  return (
    <Button mbjia onClick={() => console.log('click')}>
      确认
    </Button>
  )
}

默认主题按钮

渐变按钮

第一个组件

确认包安装和样式编译正常后，再继续接入业务组件。

4. 本地体验交互 Demo

如果想在本地看到组件实际运行效果和交互行为：

方式一：文档站本地预览

克隆组件库仓库后，启动文档站即可在浏览器中查看所有组件的效果预览、Props 表格和使用示例：

git clone https://gitee.com/vesdk/mbjia-tools.git
cd mbjia-tools
pnpm install
pnpm docs:dev

浏览器访问 http://localhost:5173，导航到基础 UI 组件页面即可查看 Button、Modal、Input 等组件的效果预览。

方式二：yarn link 本地调试

在本地业务项目中实时调试组件：

# 在组件库中 link
cd packages/ui && yarn link

# 在业务项目中引用
cd your-project && yarn link @mbjia/ui

# 调试完成后解除
cd your-project && yarn unlink @mbjia/ui
cd packages/ui && yarn unlink

yarn link 后修改组件源码会实时反映到业务项目中（配合 HMR），适合需要深度调试组件行为的场景。

业务组件接入提醒

AssetManagementModal、EveryWhereUpload、AiSearch、Payment 不是纯展示组件。它们会依赖接口、用户信息、事件总线、权限和上传 worker。

接入业务组件前，建议按顺序阅读：按场景接入、工程前置条件、业务组件总览、公共数据结构。不知道参数、出参、示例在哪里时，看 完整文档地图。