README.md · Jean-Xu/react-scaffold-admin

## React + TypeScript 中后台前端框架

### 技术栈
`React v18×` + `TypeScript` + `React-Router v6×` + `Mobx v6×` + `Ant-Design v5×` + `Express`

### 环境/特别说明
nodejs 版本默认使用 `node-v14.21.1`，如果使用了更新版本 如 `node-v18+`，需升级 `node-sass`，`npm i node-sass@9 -D`

### 命令
开发环境启动 `npm run serve` 
生产环境打包 `npm run build` 
mock接口启动 `npm run mock`

### 测试账号
用户名：**admin** 
密码：**123456**

### src目录规划
`/assets` 静态文件（图片/字体） 
`/components` 公用组件 
`/hooks` 公用hooks 
`/layout` 系统主要布局 
`/pages` 系统内容页 
`/router` 路由相关 
`/services` 接口请求、抽出公用的业务逻辑 
`/stores` mobx状态管理 
`/styles` 公用样式 
`/types` 公用ts类型 
`/utils` 工具函数 
`/vendors` 第三方库（一般不用）

### 自定义组件

**Transition**：组件切换动画 
**BtnExportExcel**：可将 json 对象数组生成为 Excel 文件并下载 
**Loader**：全局Loading 
**MediaUpload**：图片或视频文件上传，并可预览 
**SvgIcon**：svg图标使用 
**VideoPlayer**：视频播放器，集成 `video.js` 
**PageWrap**：内容模块页面渲染容器 
**PageTabs**：子路由tab导航 带动画 
**BraftRichEditor**：富文本编辑器，封装了 `braft-editor`

### 权限管理

1. 授权标识名称由 `:` 隔开，比如`sys:user:save, sys:user:delete, sys:user:update, sys:user:list, sys:user:info` 建议尽量简单命名
2. `src/config/baseConfig.ts` 中的 `HAS_PERMISSIONS` 为 `true` 时启用权限管理

### 相关文档

React 
[https://react.docschina.org/docs/getting-started.html](https://react.docschina.org/docs/getting-started.html)

TypeScript 高级类型 
[https://www.typescriptlang.org/docs/handbook/utility-types.html#partialt](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialt)

React-Router 
[https://reactrouter.com/docs/en/v6/getting-started/overview](https://reactrouter.com/docs/en/v6/getting-started/overview)

Ant Design 
[https://ant.design/components/overview-cn/](https://ant.design/components/overview-cn/) 
[v4 到 v5 迁移](https://ant.design/docs/react/migration-v5-cn)

craco 配置 
[https://craco.js.org/docs/](https://craco.js.org/docs/)

Ant Motion 
[https://motion.ant.design/index-cn](https://motion.ant.design/index-cn)

Mobx 
[https://zh.mobx.js.org/README.html](https://zh.mobx.js.org/README.html)

lodash 
[https://lodash.com/docs](https://lodash.com/docs)

react-transition-group 
[https://reactcommunity.org/react-transition-group/](https://reactcommunity.org/react-transition-group/)

braft-editor 
[https://www.yuque.com/braft-editor/be/gz44tn](https://www.yuque.com/braft-editor/be/gz44tn)

wangEditor 
[官方文档](https://www.wangeditor.com/v5/menu-config.html) 
[react demo](https://www.wangeditor.com/v5/for-frame.html#demo-2)

animejs 
[https://animejs.com/documentation](https://animejs.com/documentation/#cssSelector)

react-cropper 
[https://github.com/react-cropper/react-cropper](https://github.com/react-cropper/react-cropper) 
[https://github.com/fengyuanchen/cropperjs#options](https://github.com/fengyuanchen/cropperjs#options) 
[cropperjs-demo](https://fengyuanchen.github.io/cropperjs/)

### 踩坑总结

1. antd 日期选择框不显示中文，是忘了导入 `import 'moment/locale/zh-cn'`
2. antd 已默认支持 typescript，`@types/antd` 包已移除
3. antd 的表单实例方法 `getFieldsValue()` 当参数传入 `true` 时，只会返回有值的字段，为避免混淆一般不要传参
4. 不要直接解构 store 中的 state，会失去响应，例如 ~~`const { globalStore } = useStores(); const { userInfo, updateUserInfo } = globalStore`~~ 是错误的
5. 注意 mobx 除了异步的 **action**，默认 action 都是同步的，修改完状态能立即拿到最新值，而 react hook 的 setState 是异步的
6. 使用 `require.context` 批量导入文件不要封装为函数，因为require.context的参数只能是字面量 不能使用变量！
7. `useEffect`、`useMemo` 需要响应 mobx 状态变化，要用 `` 如 `useEffect(() => { /* do somthing */ }, [store.userInfo])`
8. mobx 异步 action 中修改状态 用 `runInAction` 包裹下
9. React 18（TS）组件有 `children`，需要在组件类型中定义该属性：`children?: ReactNode`
10. **react-router-dom v6** 原生支持 typescript，升级时移除 `@types/react-router-dom`
11. history@5 **location** 的类型 `Location`，其中 `state: unknown`，所以使用 `location.state` 时需要自己断言
12. react-router 不能像 vue-router 那样做刷新路由的功能，这里用了个小技巧 先跳转到一个预设的空白页 `navigate('/blank')`，**60**ms 后再返回 `navigate('-1')`，这样视觉上做到无感
13. react-router v6 不允许将 `<Route />` 等内置路由组件单独封装成公用组件，导入时就会报错（待研究）
14. cra 启动时 会重置 `tsconfig.json`，只需添加 `"extends": "./paths.json"` 在 `paths.json` 中添加配置
15. 富媒体编辑器用 `BraftRichEditor` 可以直接切换语言 支持多个常见语言，`wangEditor` 切换语言会卡动 不适合react环境 弃用
16. 对于报警告 `Deprecation Warning: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.` 先安装 `npm install -g sass-migrator` 然后 `cd src` 执行 `sass-migrator division **/*.scss`
17. `useLocation()` 只能用在组件中，不能用在根组件 `App.tsx`
18. **性能优化建议** 简单开销不大的子组件没必要使用 `React.memo`，计算不复杂不需要用 `useMemo`，只有用了 `React,memo` 的子组件的函数prop 才需要用 `useCallback` 包裹

**antd** `<Form.Item rule={[]} />` 表单项的基础验证规则：

```ts
interface BaseRule {
 warningOnly?: boolean;
 enum?: StoreValue[];
 len?: number;
 max?: number;
 message?: string | ReactElement;
 min?: number;
 pattern?: RegExp;
 required?: boolean;
 transform?: (value: StoreValue) => StoreValue;
 type?: RuleType;
 whitespace?: boolean;
 /** Customize rule level `validateTrigger`. Must be subset of Field `validateTrigger` */
 validateTrigger?: string | string[];
}
declare type AggregationRule = BaseRule & Partial<ValidatorRule>;
```
react相关

```jsx
const [ fileList, setFileList ] = useState(false)
setFileList((prevList) => {
  return prevList.filter(item => item.uid !== uid)
})
```

### 待做功能

1. 个人设置页（头像裁剪上传、修改基本信息、重置密码）
2. 图表demo
3. 预览excel内容

Jean-Xu/react-scaffold-admin

简介

发行版

贡献者

近期动态

Jean-Xu/react-scaffold-admin .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Jean-Xu/react-scaffold-admin