oreobuilder-cli 命令行工具

安装

全局安装 oreobuilder-cli 命令行工具

$ npm install oreobuilder-cli -g

安装成功后，在命令行中输入oreobuilder -v可以查看版本。如下：

$ oreobuilder -v
0.0.1

命令

oreobuilder-cli命令行工具支持以下命令：

• oreobuilder init

  在当前目录创建一个新的工程。在输入该命令后，将进入一个交互状态，提示输入工程名称等信息。

• oreobuilder create <name>

  进入工程目录，输入该命令可在./components目录下创建一个新的组件，组件名称<name>为必填项。

• oreobuilder start

  在工程目录，输入该命令可将编写的 demo 打包并在浏览器中预览。

• oreobuilder build

  在工程目录，输入该命令可将组件代码打包成以下资源：

  • dist/ 整个组件库打包压缩后的代码。
  • lib/ 各个组件源码经过 babel 转译后的资源，可在源码中引入并使用。
  • demo/ 组件的 demo 文件打包后的代码，按组件为单元划分，用于注册中心中的组件预览页面。
  • 其他如 package.json readme.md等文件

工程目录结构

├── README.md
├── components	// 组件库源码目录
│   ├── Button
│   │   ├── Button.js // 组件实现代码
│   │   ├── README.md // 组件的描述、api说明等
│   │   ├── demos // demo文件目录
│   │   ├── img	// 图片资源目录
│   │   ├── index.js // 组件对外暴露的出口
│   │   └── style // 组件样式目录
│   │       ├── index.js // 样式的导入导出，无需修改
│   │       └── index.less // 组件样式
│   ├── _style  // 公共样式目录
│   │   └── index.less // 定义样式变量、编写公共样式等
│   └── _utils  // 公共方法目录
├── config.json // 开发配置文件
├── manifest.json // 组件库描述文件
├── package.json
├── static // 静态资源目录
│   └── hightlight
│       ├── highlight.pack.js
│       └── styles
└── tsconfig.json

文件说明

config.json

描述组件库在开发过程中的相关配置。

| 字段名称 | 说明 | 类型 | 默认值 | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------- | ---------------- | | port | 启动本地预览时的端口号 | sting | "8090" | | autoTemplate | 启动本地预览时，是否自动生成预览框架 | true | true | | sourcePath | 组件库中组件源码所在目录 | string | './components' | | type | 组件库使用的是 js 代码还是 ts 代码 | 'js'|'ts' | js | | lib | 避免将一些很通用的模块打包进你发布的 library 里，相当于 external 的模块声明。可通过配置加入 cdn 地址以在本地预览时引入。 | array | - | | extraImport | 本地预览时额外导入的 js/css 文件 | object | - | | buildImport | 构建组件库时额外导入的 js/css 文件和导出文件 | object | - | | libPath | 组件库构建 lib 文件的根路径 | string | 同 sourcePath | | device | 组件库适配设配 | 'PC'|'mobile' | 'PC' | | previewUrl | 移动端预览时扫码打开页面的 url | string | '127.0.0.1:8090' | | plugins | webpack | array | [] | | useManifest | 为 true 时，产出的文件中每个组件会引入 manifest 并与组件使用 ReactWrapper 连接；为 false 时产出单纯的 react 组件 | Boolean | true | | excludeNidAndUiType | 组件不在最外层套一层 div 并添加 nid 和 uitype | Boolean | true | | excludeNidAndUiTypeComp | excludeNidAndUiType 为 false 时，不添加 div 的组件名称数组 | array | [] | | staticPropsMap | 添加 div 后再去添加属性的映射关系 | object | {} | | iconMap | 为对应组件添加 icon 描述，设计器使用，非必需 | object | {} | | setExtendComp | 接入 MDF 运行态渲染使用，默认为 true，会自动注册组件到渲染引擎 | Boolean | true | | extraCss | 控制是否单独打包 css | Boolean | true | | outputConfig | 对应 webpack 的 output 属性 | object | {} | | buildBase64 | 控制是否打包时讲图片转换为 base64 | Boolean | false |

其中，工具中已经默认将 react、react-dom 作为依赖库，且不可修改，如对react的描述为(lib 属性类型)：

{
  "key": "react", // 对应webpack中externals属性的key值
  "value": "React", // 对应webpack中externals属性的value值
  "js": "//design.yonyoucloud.com/static/react/16.8.4/umd/react.production.min.js", // 在本地预览时js代码的cdn地址
  "css": "" // 在本地预览时css代码的cdn地址
}

extraImport 属性中 js 和 css 属性的值均为字符串形式，需要注意对引号的转译，示例如下：

{
  "js": "<script src=\"//design.yonyoucloud.com/static/console-polyfill/console-polyfill.js\"></script><script src=\"//design.yonyoucloud.com/static/es5-shim/es5-shim.min.js\"></script>",
  "css": "<link href=\"./index.css\" rel=\"stylesheet\">"
}

buildImport 属性示例如下:

"buildImport": {
    "js":["import * as AntdMobile from 'antd-mobile'"],
    "css":["@import '~antd-mobile/dist/antd-mobile.css'"],
    "export":[
      "AntdMobile"
    ]
  }

staticPropsMap 属性示例如下：

"staticPropsMap": {
    "ListView": "DataSource"
  }

可将 ListView 的 DataSource 属性挂载到经过 ReactWrapper 包裹后的组件上。

manifest.json

描述了组件库整体的信息

| 字段名称 | 说明 | | ----------- | ------------------------------------------------------------------------------------ | | name | 开发的组件库的名称，且在组件打包后可以通过__[name]__的形式注入到全局对象中 | | version | 组件库的版本 | | keyword | 组件库的关键字 | | description | 对组件库的描述、介绍 | | components | 描述了组件库中打包后组件的结构。可通过此属性灵活配置需要打包的组件、组件的结构关系。 |

一个文件示例如下：

{
  "name": "ybui",
  "version": "0.0.1",
  "keyword": "demo library ybui",
  "themes": "A demo component library.",
  "description": "metaui-mobile组件库",
  "components": {
    "basic": {
      "Col": "./components/Col",
      "Row": "./components/Row"
    },
    "other": {
      "Button": "./components/Button"
    }
  }
}

若使用oreobuilder build命令打包，则可以直接在页面中引入打包后的 js 文件，使用__yonui__.basic.Col去使用Col组件，也可以 npm 发包或直接引用 dist 文件等方式使用。

注意事项

• 编写组件时组件代码中无需手动引入样式文件

  执行oreobuilder build 时，会从./components/<Component>/index.js打包 js 文件，从./components/<Component>/style/index.js打包样式文件，生成的结果中 js 代码和 css 代码分离。

  因此，在编写 demo 的过程中，需要有以下代码以保证 demo 中的样式正确：

  ...
  import MyComponent from '../index'; // 引入组件代码
  import '../style'; // 引入组件样式代码
  import './index.less'; // 引入demo文件的样式代码
  ...

• demo 代码的注释标识

  在每个 demo 代码中，需要在开头用注释描述该 demo 的信息。如：

  /**
   * @name: Button组件的基本使用
   * @description: Button组件使用size属性控制大小，使用colors属性控制主题色。
   */

  以上将在预览页面渲染成对应的元素，因此不可忽略。

使用案例

以下将描述整个流程：

• 安装工具

  使用npm install oreobuilder-cli -g全局安装命令行工具。

• 创建工程

  在需要的目录，打开命令行，键入oreobuilder init命令，输入工程名、作者名、编码类型(js or ts)等信息，创建新的工程。

• 创建组件

  进入工程目录，先安装依赖（推荐使用 npm install）。之后使用create命令创建组件，假设组件名为 MyComponent。禁止使用下划线开头，创建时将自动将组件名称首字母大写。

  $ cd Demo
  $ npm install
  ...
  $ oreobuilder create MyComponent
  ...Component MyComponent was successfully created.

• 编码

  在组件对应的目录下编码，建议将组件代码写在单独的文件中如MyComponent.js中，通过index.js作为统一的出口对外暴露。组件的样式文件写在./components/MyComponent/sytle/index.less文件中，公共样式代码写在./components/_style/index.less中。js 代码中无需手动引入样式文件。

  编码 demo 时，参考注意事项。

• 本地预览

  在 manifest.json 文件的 components 属性中配置组件的入口。如：

  components:{
    "MyComponent": "./src/components/MyComponent"
  }

  在工程目录下，执行oreobuilder start命令启动本地预览。

  $ oreobuilder start
  ...

• 打包发布

  在工程目录下，执行oreobuilder build命令将打包组件库文件。

• 输出 manifest

  在组件目录下有一个 manifest.tsx 文件，导出组件的 manifest 信息。在 index.tsx 中无需关联。