# react-scaffold-admin

**Repository Path**: mrfront/react-scaffold-admin

## Basic Information

- **Project Name**: react-scaffold-admin
- **Description**: react + typescript 中后台前端框架（有权限系统）
- **Primary Language**: TypeScript
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 17
- **Forks**: 0
- **Created**: 2022-01-23
- **Last Updated**: 2024-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, TypeScript, Ant-Design, mobx

## README

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

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

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

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

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

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

### 自定义组件

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

### 权限管理

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<br>
[https://react.docschina.org/docs/getting-started.html](https://react.docschina.org/docs/getting-started.html) <br>

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

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

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

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

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

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

lodash<br>
[https://lodash.com/docs](https://lodash.com/docs)

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

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

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

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

react-cropper<br>
[https://github.com/react-cropper/react-cropper](https://github.com/react-cropper/react-cropper) <br>
[https://github.com/fengyuanchen/cropperjs#options](https://github.com/fengyuanchen/cropperjs#options) <br>
[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.` <br>先安装 `npm install -g sass-migrator` <br>然后 `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内容