npm package: @mogul/components
Description: React UI components based on Mobx && Antd, help freshesx to easy build admin pages
Author: zhangqing
Latest version: 0.24.3

<p align="center">
  <a href="https://freshesx.github.io/mogul-website/"><img src="./assets/logo/logo.png" height="200" width="200" alt="mogul logo"/></a>
</p>

<h2 align="center">
  @mogul/components 中后台 UI 框架
</h2>

[![NPM version](https://img.shields.io/npm/v/@mogul/components.svg?style=flat-square)](https://www.npmjs.com/package/@mogul/components)
[![CircleCI](https://circleci.com/gh/freshesx/mogul.svg?style=svg&circle-token=37fb5b4463a5bbc51ad8a291cecb8af30a0c1349)](https://circleci.com/gh/freshesx/mogul)
[![NPM downloads](https://img.shields.io/npm/dm/@mogul/components.svg?style=flat-square)](https://www.npmjs.com/package/@mogul/components)
[![License](https://img.shields.io/npm/l/@mogul/components.svg?style=flat-square)](https://www.npmjs.com/package/@mogul/components)
[![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@mogul/components.svg)](https://www.npmjs.com/package/@mogul/components)
[![Github Tag](https://img.shields.io/github/tag/freshesx/mogul.svg)](https://github.com/freshesx/mogul)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![style: styled-components](https://img.shields.io/badge/style-%F0%9F%92%85%20styled--components-orange.svg?colorB=daa357&colorA=db748e)](https://github.com/styled-components/styled-components)
[![GitHub stars](https://img.shields.io/github/stars/freshesx/mogul.svg?style=social&label=Stars)](https://github.com/freshesx/mogul)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/1f498cc05ed34dfeb5553c5caef5becf)](https://www.codacy.com/app/JennerChen/mogul?utm_source=github.com&utm_medium=referral&utm_content=freshesx/mogul&utm_campaign=Badge_Grade)
[![Depfu](https://badges.depfu.com/badges/86a1bcd8ce413602052d70a1833b0561/overview.svg)](https://depfu.com/github/freshesx/mogul?project_id=7201)
<a href="#badge">
<img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
</a>
[![996.icu](https://img.shields.io/badge/link-996.icu-red.svg)](https://996.icu)

# 特性

- :+1: 现代前端技术: react + mobx + antd + styled-components
- :clap: 聚焦中后台
- :hatched_chick: 基于 react-router 路由集成

> [create-mogul-app](https://github.com/freshesx/mogul-scripts)

- :100: 模板示例: 精心设计的模板
- :high_brightness: 效率优先: 源于实践,实用的才是最好的
- :cat: 开箱即用: 基于 create-react-app,深度优化,完全 0 配置

## install

```bash
yarn add @mogul/components
```

> 强烈推荐和 [create-mogul-app](https://freshesx.github.io/mogul-website/docs/create-mogul-app) 脚手架 一起使用,

```bash
npx @mogul/create-mogul-app <project-name>
```

> 不支持直接使用脚本的方式引用

详见:

- [文档](https://freshesx.github.io/mogul-website/)
- 在线例子:[![storybook](https://cdn.jsdelivr.net/gh/storybooks/brand@master/badge/badge-storybook.svg)](https://mogul.beaf.tech/)

## FAQ

### 与 `antd` , `create-react-app` 的关系

`mogul` 注重后台管理页面的开发， 基于当前流行的开源库，二次封装。尽量保证不侵入引用库

@mogul/components 是 `antd` 的补充, 增加了一些关于后台管理页面的组件。

@mogul/mogul-scripts: 是基于`create-react-app`封装的 0 配置脚手架, 使用方式尽量与`CRA`保持一致。

### Why mobx 为什么使用 Mobx 作为状态管理库

当前主流状态管理有 `Redux`, `Mobx`, `Relay`

1. Redux: 通常是 react 中最欢迎的，但是组件库并不一定需要。主要原因有一下
   Redux 强调清晰的数据流。在实际开发中，你会发现拖慢了开发进度, 而且你需要优化频繁更新的组件，这都是额外的工作量。Redux 使用单数据中心模式, 不适合后台组件的设计逻辑。中台系统存在大量表单, 如果严格按照 Redux 流程开发, 应该所有的开发者都会发疯的。

2. Mobx: 通过 mobx-react 使得 react 组件拥有双向数据流的功能, 能够大幅度减少 setState 的使用, 数据共享只需 provider 就可以传递到子组件, 而且自动执行 setState 刷新组件。在开发组件的工程中, 特别是业务逻辑代码, 几乎从来不需要手动优化 `componentWillReceiveProps` 等方法, 这大大节省了开发时间。更高的代码可读性, 使用 es6 class+装饰器(decorators), 使得代码非常清晰。 react 只做 ui 渲染部分, 极少 setState, 不需要跨越不同目录寻找代码, 数据逻辑在 class 中完成, 自动渲染到 ui 层。Mobx 主要缺点他会修改 transform 数据结构,变成 obserable, 这会增加测试复杂度。同时,个人原因, 我更喜欢纯粹的数据, Mobx 施加了太多魔法。这和 vue 类似。

3. Relay: Facebook 的 Relay 使用 graphql 当做数据获取方式, 他能够一次性获取装饰组件所有需要的数据,内置数据性能优化功能, 通过 mutations 触发修改,自动重新获取数据, 能够快速开发组件, 个人更看好 Relay 相对于 Redux、Mobx。But, 必须使用 graphql, 这不符合国情, 所以没有选用。

4. React hooks: React v16.8.0 加入了全新的 React hooks 功能。主要解决 class 组件模板过多, 组件层级太深, this 不明确，生命周期冗余等问题。虽然官方没有说明, class 组件会被废弃, 但是可以预见在将来 React 开发中, 会主要使用 React hooks 方式开发。故使用 React hooks 替换 class 组件是趋势。但是, 因为 hooks 问世不久，缺少很多 class 相关生命周期方法的 polyfill, 故暂时不推荐使用。又因为大量内部项目依赖于 mobx, 故没有替换 mobx 作为主状态管理库的打算。

### Why antd + styled-components

使用`antd`主要因为现有环境所致, `antd`足够优秀且组件,中文文档丰富。另外一个很重要的原因现在公司内部很多遗留项目,使用的是 antd,为了保持风格统一。
mogul 只使用了`antd`基本的组件且不侵犯`antd`中的组件, 如果业务需要将来可以快速替换成 material, 或者 semantic、bootstrap。
css 可选择性很多, inline, css-module, styled-components。styled-components 可以把 css 当成 react 组件一样编写, 入门门槛低且与 js 共享所有工具。个人非常看好 styled-components 成为最后 react 样式的标准实现

### 模板似乎还不够具有生产力

生产力需要配合实际业务逻辑。我们内部使用 mogul 还会再对其进行第二次模板化, 但是这包含公司的业务逻辑,所以抱歉。那是不是不可使用? 不是的, mogul 本身是对 antd 的补充, antd 有些组件过于复杂, 而 mogul 简化了流程,默认的配置在绝大部分情况下就是最优的,起码对我们。你不需要额外去找文档即可编写，这能节省大量时间。wellcome fork!

## 贡献 Mogul

> Mogul 主要用于食行使用，故暂时不开放非成员以外的 PR 合并。

- [CONTRIBUTING.md](./CONTRIBUTING.md)

## 相关资料

- [mogul-scripts](https://github.com/freshesx/mogul-scripts)
- [mogul-website](https://github.com/freshesx/mogul-website)
- [examples](https://mogul.beaf.tech/)

食行生鲜运营平台开发部出品