diff --git a/docs/guide/about.md b/docs/guide/about.md index 4bebdc724f..207996e288 100644 --- a/docs/guide/about.md +++ b/docs/guide/about.md @@ -31,6 +31,10 @@ cover: https://gw.alicdn.com/tfs/TB1vBRYaVOWBuNjy0FiXXXFxVXa-2558-1306.jpg 毫无疑问是需要的，我们在努力降低前端开发的门槛，但一些基础的前端知识还是需要具备的，比如 JavaScript 的基础预发、前后端如何通信等。为了便于快速入门前端知识，我们整理了一份 [前端基础知识](/docs/guide/resource/front-basic.md)，希望能帮助到开发者。 +#### 资深前端同学是否适合使用飞冰？ + +在 GUI 工具基础上，飞冰还提供了 [CLI 版本](/docs/guide/start#使用%20CLI%20方式创建项目)，因此如果你不需要 GUI 的能力，依然可以完全使用 CLI 的链路开发项目，同时使用到飞冰的项目最佳实践、工程工具以及状态管理方案。 + #### 飞冰（ICE）的浏览器兼容策略是怎样的？ 飞冰官方 React 物料默认使用 React 16+，其需要的最低 IE 版本为 11，如果您需要在以下的版本使用，您可能需要引入一些 polyfill 来支持 `Map`, `Set` 等特性。参考[React 官网说明](https://reactjs.org/blog/2017/09/26/react-v16.0.html#javascript-environment-requirements)。 diff --git a/docs/guide/dev/react-materials.md b/docs/guide/dev/react-materials.md index 58bb836a1a..bed6a1d24d 100644 --- a/docs/guide/dev/react-materials.md +++ b/docs/guide/dev/react-materials.md @@ -9,7 +9,7 @@ order: 1 ### 基础组件 -使用由阿里巴巴 [Fusion 团队](https://fusion.design) 开源的 [Next 组件](https://ice.work/component/affix)，包括按钮、弹窗、下拉等组件。Next 组件足够丰富且稳定，同时在国际化、无障碍方面做了较多沉淀，另外 Next 组件最大的特性是具有非常强大灵活的主题定制能力，使其可以满足更多的业务场景，具体可参考文档 [配置主题](/docs/cli/basic/theme.md)。 +使用由阿里巴巴 [Fusion 团队](https://fusion.design) 开源的 [Next 组件](https://ice.work/component/affix)，包括按钮、弹窗、下拉等组件。Next 组件足够丰富且稳定，同时在国际化、无障碍方面做了较多沉淀，另外 Next 组件最大的特性是具有非常强大灵活的主题定制能力，使其可以满足更多的业务场景，具体可参考文档 [配置主题](/docs/cli/plugin-list/fusion)。 安装组件依赖： diff --git a/docs/guide/resource/migrate.md b/docs/guide/resource/migrate.md index aa1a601098..47f0d12303 100644 --- a/docs/guide/resource/migrate.md +++ b/docs/guide/resource/migrate.md @@ -1,162 +1,75 @@ --- -title: icekit pro 模板升级指南 +title: ICE 脚手架升级指南 order: 4 --- -飞冰将前端开发领域的最佳实践集成在 icekit pro 模板中，pro 模板到目前为止发过 3 个版本，每个版本之间的 breaking change 主要在于路由配置方面，以下列出了不同版本间的差异点： - -## 版本差异点 - -### icekit 1.x -- 路由配置放在 `src/routerConfig` 中 -- 路由配置中只包含页面路由配置，不支持路由按 Layout 分组，所有路由平铺 - -```javascript -const routerConfig = [ - { - path: '/dashboard/monitor', - component: Dashboard, - }, - { - path: '/chart/general', - component: Charts, - } -]; -``` - -- Layout 路由在 `src/router.js` 中 - -```javascript -// 按照 Layout 分组路由 -const router = () => { - return ( - - - - - ); -}; - -``` - -- 重定向路由与未匹配路由定义在 Layout 组件中，例如 BasicLayout 的路由为 `src/layouts/BasicLayout/MainRoutes.js` - -```javascript - - {/* 渲染权限路由表 */} - - {routerData.map(this.renderAuthorizedRoute)} - - {/* 路由重定向，嵌套路由默认重定向到当前菜单的第一个路由 */} - {redirectData.map((item, index) => { - return ; - })} - - {/* 首页默认重定向到 /dashboard */} - - - {/* 未匹配到的路由重定向到 404 */} - - -``` - -### icekit 2.x -- 相对于 1.x 对路由配置作了收敛，将 Layout 配置及重定向、未匹配路由全部收敛到 `src/routerConfig.js` 中 - -```javascript -const routerConfig = [ - { - path: '/', - component: BasicLayout, - children: [ - { - path: '/dashboard', - component: Dashboard, - }, - { - path: '/', - redirect: '/dashboard', - }, - { - component: NotFound, - }, - ], - }, -]; -``` - -- 路由渲染逻辑全部收敛到 `src/router.jsx` 中 - -### icekit 3.x -- 与 2.x 唯一的区别是 `routerConfig` 与 `menuConfig`, `dataSourceConfig` 进一步收敛到 `config` 目录中，目录结构如下： - -```markdown -└── config/ # 配置信息 - ├── dataSource.js # 数据源配置 - ├── routes.js # 路由配置 - └── menu.js # 导航菜单配置 -``` +飞冰将前端开发的最佳实践集成在脚手架中，主要包含目录结构、路由配置、状态管理等相关内容，脚手架截止目前总共有三个版本，这三个版本之间有一些微小的 break change，如需升级请参考本文档。 +## 版本差异 + +### 1.x + +初始版本，存量项目较多，[示例项目](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.0/)，主要包含以下特点： + +- 推荐使用 Class Component +- 构建工具 ice-scripts 有 1.x&2.x 两个版本 +- 路由配置放在 `src/routerConfig.js` 中，路由渲染与 Layout 耦合，不支持路由按 Layout 分组，不支持路由嵌套，相关代码： + - 路由配置：[代码](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.0/src/routerConfig.js) + - 路由入口：[代码](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.0/src/router.jsx) + - 路由渲染：[代码](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.0/src/layouts/BasicLayout/MainRoutes.jsx) + +### 2.x + +过渡版本，变更点较多，存量项目较少，[示例项目](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.8/)，主要包含以下特点： + +- [兼容]推荐使用 Function Component + React Hooks +- [兼容]通过 `@ice/spec` 收敛 lint 相关配置，统一项目的 lint 命令 +- [兼容]统一将 `src/` alias 到 `@`，方便 `import` 写法 +- [兼容]推荐通过基于 React Hooks 的状态管理方案 [icestore](https://github.com/ice-lab/icestore) +- [兼容]构建工具统一升级到 ice-scripts@2.x +- [不兼容]路由配置放在 `src/routerConfig.js` 中，支持通过 Layout 分组，路由嵌套等能力，路由相关代码： + - 路由配置：[代码](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.8/src/routerConfig.js) + - 路由渲染：[代码](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@2.0.8/src/router.jsx) + +### 3.x + +最新版本，在 2.x 基础上做了配置文件的收敛，[示例项目](https://unpkg.com/browse/@icedesign/hr-management-admin-scaffold@3.0.4/)，相对 2.x 改动点： + +- [兼容]将 react-router-dom 升级到 5.x 解决 warning 问题 +- [不兼容]将配置文件收敛到 `src/config/` 目录，`routerConfig.js -> config/routes.js`，`menuConfig.js -> config/menu.js` ## 升级指南 -官网上的文档都是基于最新的 3.x 版本目录规范，如果您的项目是基于旧版本的 icekit，请按照以下步骤升级到 3.x 版本： +### 1.x 升级到 3.x -### 1.x 升级 3.x -1. 按照 3.x 目录规范将数据源配置、路由配置、导航菜单配置移入 `src/config/` 目录下 +1. 按照 3.x 目录规范将数据源配置、路由配置、导航菜单配置移入 `src/config/` 目录下，并修正引用这些文件的路径 2. 按照路由设计文档中的[路由配置](/docs/guide/dev/router#路由配置)部分，升级 `src/config/routes.js` 中的路由配置 -3. 按照路由设计文档中[路由生成](/docs/guide/dev/router#具体使用)部分，升级路由渲染逻辑文件 `src/router.jsx`，并将 `src/index.jsx` 中路由调用改成如下方式： - - ```javascript - ... - import router from './router'; - ... - - ReactDOM.render( - - {router()} - , - ICE_CONTAINER - ); - ``` - -4. 将 Layout 中路由配置部分 `` 删除，并替换成 `children` - - ```javascript - // 修改前 - -
- - - - - -