Iceworks 默认提供了基于 create-react-app 的模板，该模板可以无缝使用飞冰组件、区块、模板等能力，参见文档。

如果上述模板不能满足你的需求，请参考本篇文章，本文讲述如何在使用 create-react-app 创建的项目中使用飞冰相关的物料。PS: 其他工程工具原理相同。

初始化项目

使用 npx 命令执行 create-react-app 创建一个项目：

  1. npx create-react-app my-app
  2. cd my-app
  3. npm start

npx 命令在 npm 5.2+ 自带，如果没有 npx 您可能需要按照官方文档操作

此时浏览器会打开本地调试地址 http://localhost:3000/ 。

引入组件

  1. # 根据组件文档，安装对应的组件。
  2. npm install @icedesign/base @icedesign/img --save
  4. # create-react-app 支持 sass https://facebook.github.io/create-react-app/docs/adding-a-sass-stylesheet
  5. tnpm install node-sass --save-dev

修改 src/App.js，引入 Button 和 Img 组件。

  1. import React, { Component } from 'react';
  2. // 全量引入基础组件样式
  3. import '@icedesign/base/index.scss';
  4. // 引入基础组件脚本，无工程辅助情况下 import { Button } from '@icedesign/base'; 会引入所有 js
  5. import Button from '@icedesign/base/lib/button';
  6. // 引入业务组件脚本
  7. import Img from '@icedesign/img';
  8. // 引入业务组件样式
  9. import '@icedesign/img/lib/style.js';
  11. import './App.css';
  14. const image =
  15.   'https://img.alicdn.com/tfs/TB1saOBbYGYBuNjy0FoXXciBFXa-218-58.png';
  17. class App extends Component {
  18.   render() {
  19.     return (
  20.       <div className="App">
  21.         <Button type="primary">Button</Button>
  22.         <Img src={image} />
  23.       </div>
  24.     );
  25.   }
  26. }
  28. export default App;

现在你应该能看到页面上已经有了蓝色的 Button 组件，接下来就可以继续选用其他组件开发应用了。

其他开发流程你可以参考 create-react-app 的官方文档。

这种方式引入的基础组件样式为全量引入，如果需要按需引入请看下面文档。

自定义按需引入

上面的方法虽然能够正常运行组件，但是可以发现几个问题：

  • 基础组件的样式需要全量引入的
  • 引入基础组件需要额外增加 lib/button 的二级路径并且每个组件都需要单独 import
  • 业务组件需要分开引入脚本和样式

要解决这些问题，我们需要对 create-react-app 进行一些工程定制。我们建议使用社区流行的 react-app-rewired 进行自定义配置。

首先安装 react-app-rewired

  1. npm i react-app-rewired --save-dev

修改 package.json 文件的 scripts 字段

  1. {
  2.   "scripts": {
  3.     "start": "react-app-rewired start",
  4.     "build": "react-app-rewired build",
  5.     "test": "react-app-rewired test --env=jsdom"
  6.   }
  7. }

在您的项目根目录创建 config-overrides.js 文件来修改默认配置。

使用 babel-plugin-import 实现按需加载

babel-plugin-import 是一个用于按需加载组件代码和样式的 babel 插件，现在我们尝试安装它并修改 config-overrides.js 文件。

  1. npm i babel-plugin-import --save-dev
  1. + const { injectBabelPlugin } = require('react-app-rewired');
  3.   module.exports = function override(config, env) {
  4. +   config = injectBabelPlugin(['import', {
  5. +     libraryName: '@icedesign/base'
  6. +   }], config);
  7.     return config;
  8.   };

使用 webpack-plugin-import 实现样式自动引入

webpack-plugin-import 是用于自动加载样式的 webpack 插件，它的原理是对引入模块路径下存在 style.js 的样式进行自动加载，这意味着您可能需要同时配置 less 或 sass 等预处理器的 loader。

修改 config-overrides.js 的内容

  1. // ...
  2. const WebpackPluginImport = require('webpack-plugin-import');
  4. module.exports = function override(config, env) {
  5.   // ...
  6.   config.plugins.push(
  7.     new WebpackPluginImport([
  8.       {
  9.         libraryName: /^@icedesign\/base\/lib\/([^/]+)/,
  10.         stylePath: 'style.js',
  11.       },
  12.       {
  13.         libraryName: /@icedesign\/.*/,
  14.         stylePath: 'style.js',
  15.       },
  16.     ])
  17.   );
  18.   // ...
  19.   return config;
  20. };

配置 sass-loader 和 ice-skin-loader

ICE 官方提供的组件依赖了 Sass 作为 CSS 预处理器，所以您需要手动配置并引入 sass-loader。同时 ICE 使用了 ice-skin-loader 支持自定义皮肤的定制。首先安装以下依赖：

  1. npm i @icedesign/skin --save
  2. npm i sass-loader node-sass ice-skin-loader --save-dev

在根目录创建 rewire-scss.js 文件，添加以下内容。

  1. const getRules = (config) =>
  2.   config.module.rules.find((rule) => Object.keys(rule).includes('oneOf')).oneOf;
  3. const findFileLoaderRuleFn = (rule) =>
  4.   typeof rule.loader === 'string' && rule.loader.includes('file-loader');
  5. const findStyleLoaderRuleFn = (rule) =>
  6.   rule.test.toString() === /\.css$/.toString();
  8. function rewireSass(config, env, sassOptions = {}) {
  9.   // find the non-javascript ruleset in the webpack config
  10.   const rules = getRules(config);
  12.   // find the file-loader and add a rule excluding sass files from being loaded as text
  13.   config.module.rules[1].oneOf
  14.     .find(findFileLoaderRuleFn)
  15.     .exclude.push(/\.scss$/);
  17.   // find the current rule for loading css files
  18.   const styleLoaderRule = rules.find(findStyleLoaderRuleFn);
  20.   // allows the test to be pre-defined by react-scripts as an array or a single regex
  21.   const currentTests = Array.isArray(styleLoaderRule.test)
  22.     ? [...styleLoaderRule.test]
  23.     : [styleLoaderRule.test];
  25.   // add regexes for scss files
  26.   styleLoaderRule.test = [...currentTests, /\.scss$/, /\.sass$/];
  28.   styleLoaderRule.use.push({
  29.     loader: require.resolve('sass-loader'),
  30.     options: sassOptions,
  31.   });
  32.   styleLoaderRule.use.push({
  33.     loader: require.resolve('ice-skin-loader'),
  34.     options: {
  35.       themeFile: require.resolve('@icedesign/skin'),
  36.     },
  37.   });
  39.   return config;
  40. }
  42. module.exports = rewireSass;

修改 config-overrides.js 的内容

  1. // ...
  2. const rewireSass = require('./rewire-scss');
  4. module.exports = function override(config, env) {
  5.   // ...
  6.   config = rewireSass(config);
  7.   // ...
  8.   return config;
  9. };

使用组件

在项目的任意 js 文件中，您都可以使用类似如下的方法直接按需引入某一组件，不用担心全量引入和样式缺失的问题。

  1. import { Button } from '@icedesign/base';
  2. import Img from '@icedesign/img';
  4. <Button type="primary">ICE</Button>;

如何通过 Iceworks 生成 create-react-app 项目

如果你觉得使用 create-react-app 自定义太麻烦，我们也提供了基于 Iceworks 模板创建项目的流程生成 create-react-app 项目，使用 react-app-rewired 进行自定义配置，支持按需引入飞冰基础组件，添加区块。

初始化项目

在 Iceworks 模板界面选择 create-react-app 模板，以该模板创建项目

Iceworks

预览

创建项目后，可以在 Iceworks 项目界面启动调试服务, 会自动打开浏览器窗口，看到如下页面说明创建项目成功

create-react-app

添加区块

使用 Iceworks create-react-app 模板创建的项目与官方 create-react-app 模板基本保持一致，不同的点在于使用了 react-app-rewired 进行自定义配置，支持按需引入 ICE 基础组件，目录结构如下：

目录结构

  1. .
  2. ├── README.md
  3. ├── .gitignore
  4. ├── config-overrides.js
  5. ├── package.json
  6. ├── public
  7. │   ├── favicon.ico
  8. │   ├── index.html
  9. │   └── manifest.json
  10. ├── rewire-scss.js
  11. └── src
  12.     ├── App.css
  13.     ├── App.js
  14.     ├── App.test.js
  15.     ├── index.css
  16.     ├── index.js
  17.     ├── logo.svg
  18.     └── registerServiceWorker.js

添加区块

通过 Iceworks 新建页面添加的区块默认会在项目 src 下新建 pages 目录，用于存放添加的区块，如添加一个 TabTable 区块后，目录结构如下：

  1. .
  2. └── src
  3.     ├── pages/     // 新增 pages 目录
  4.     ├── App.css
  5.     ├── App.js
  6.     ├── App.test.js
  7.     ├── index.css
  8.     ├── index.js
  9.     ├── logo.svg
  10.     └── registerServiceWorker.js

使用 create-react-app 模板创建的项目默认只支持添加区块；接下来，可以按照你熟悉的开发方式自定义开发。