区块物料方案（umi block）

[yutingzhao1991]

相关 ISSUE：

#628

• 支持基础的 umi block 功能 feat: umi block #1402
• 考虑 singular = true 的情况 feat: add plugin api for umi block #1436
• 使用配置路由时自动添加路由 feat: umi block #1402
• 支持 layout feat: support --path with umi block #1444
• 提供一些插件的方法提供给 bigfish（蚂蚁内部基于 umi 的框架） 使用 feat: add plugin api for umi block #1436
• create-umi 中提供开发区块的模板 feat: support create umi block create-umi#15
• 支持 _mock.js feat: support _mock.js in page(s) folder #1503
• 支持在页面中添加 locales feat: support set locale file in page folder #1513
• 文档 doc: init umi block doc #1561

区块定义

一个前端页面的代码，开发者可以添加它到使用 umi 开发的前端项目中并做自己的修改使用。

区块使用

用户可以使用 umi block https://github.com/umijs/umi-materials/demo 来使用区块。

执行该命令后物料的代码将会被下载复制到用户的代码中，用户可以直接通过路由访问（一期暂时先不考虑配置式路由），针对配置式路由的方案再继续讨论细化。

物料目录结构

物料的来源应该是多样话的，它可以是：

• 一个 npm 包
• 一个 HTTP 地址 // 需要是一个 gitlab 或者 github 的地址，需要解析后 clone 下来
• 一个 git 地址 // 单独的一个 git 仓库
• 一个本地文件路径 // 用于调试

不管是什么，这个地址指向的位置下必须包含如下的目录结构：

- root
  - src // 文件夹，物料的内容
     - index.js // 页面的入口
  - @ // 文件夹，物料附加资源，会原封不动的 merge 到项目 src 下，用于类似 pro 这样成体系的物料系统
  - thumb.[png|jpg] // 物料的缩略图
  - package.json

其中 package.json 文件相关内容如下：

{
  name: '@umi-blocks/demo',
  description: '区块描述',
  // ... 更多其他 npm 包的相关定义
  dependencies: {
    // dependencies 里面是区块运行时阶段的依赖，比如 antd g2 这些包的依赖
    antd: '^3.0.0',
  },
  devDependencies: {
    // 用户调试物料时候的依赖，和物料没有直接关系，可以提供基于 umi 的开发方案
  },
  scripts: {
    // 开发物料调试时的命令，和物料没有直接关系
  }
}

在这个结构下，实际上飞冰的物料也满足这个结构，可以直接拿来用。

实现

官方区块仓库

新增一个 https://github.com/umijs/umi-blocks 的仓库，用做是官方的区块仓库。类似飞冰的 https://github.com/alibaba/ice/tree/master/react-materials/blocks 。

umi plugin: blocks

基于 yeoman-generator 实现的 umi 插件，用于下载区块代码到项目中，主要操作如下：

1. 下载区块，这里可以做下缓存，如果是 git 仓库，那么第二次就可以是 git pll ，提高速度
2. 区块/src/* -> 项目/src/pages/[物料名称]/*
3. 区块/@/* -> 项目/src/*

其中第一步，以物料的 package.json 中的 name 作为 pages 里面的文件夹名称，如果是类似 @umi-blocks/demo 这样的者以 / 分隔，去最后一位作为有效名称。也可以通过参数 --name 来指定名称。

其中第二步，主要考虑到类似 antd pro 这样的项目，想要将项目中的各个页面拆分为一个个物料，那么可能页面中还引用了一些不在页面文件夹下的内容。那么需要将这部分内容放到 @ 目录下，在 umi-material 工具下载时会做一个合并（关于冲突可以后面慢慢改进，前期最简单的方案就是如果发现已经有了就提示用户跳过或者覆盖，让用户手动处理）。

该插件内置到 umi 中，提供 umi block 命令。

umi-plugin-block-dev

用于物料开发，添加该插件后，运行 umi dev 会自动把 src 作为唯一的主路由，把 @ 别名修改到 @ 目录。

[xiaoxiangmoe]

@ 文件夹的作用是什么呢？
物料用于 ant-design-pro 之类的中后台项目，有计划使用 monorepo 吗？
物料会生成 .d.ts 文件来支持 TypeScript 吗？

[yutingzhao1991]

@ 文件夹的作用是什么呢？

@ 对应就是 umi 别名 @/ 对应的项目 src 目录。后续计划 antd pro 的每个页面都会拆分为一个物料，针对这种物料，可能物料里面会 import 除了页面外的一些内容。比如 @/utils/request.js。这个就是针对这种场景的。

物料用于 ant-design-pro 之类的中后台项目，有计划使用 monorepo 吗？

monorepo 这个是什么意思？

物料会生成 .d.ts 文件来支持 TypeScript 吗？

物料可以是 ts 的，umi 只是做了一个代码拉取，但是不会额外生成 d.ts

[yutingzhao1991]

补充关于 git 缓存的问题：

在下载物料时，为了提高速度，会缓存 git 仓库，如果已经下载过那么只需要做 pull，但是这样可能会在某些情况下 pull 失败等情况下，需要提供参数给用户需要清空缓存。想到两个方案：

• 提供 umi m clean 命令清空缓存目录。
• 添加参数，比如 umi m https://github.com/umijs/umi-materials/demo --no-cache。

[sorrycc]

为啥会 pull 失败？失败的时候重新执行命令？

[yutingzhao1991]

比如极端情况下缓存目录的 git 仓库被修改，因为本地修改没有提交，那么 pull 就会失败。或者由于某种以后可能出现的原因 git 仓库的缓存出问题的情况下最好能够提供用户清空缓存的方案（想到这，或许就让用户手动删除对应的缓存文件夹就好了）。

[yutingzhao1991]

新增两个参数：

--name 指定物流下载到 page(s) 下的目录名称，默认使用物流 package.json 中的 name 的有效部分。
--npm-client 自动安装依赖时候使用的 npm ，比如可以指定为 cnpm 或者 yarn。

[tolerance-go]

物料会提供可视化市场吗？类似 http://scaffold.ant.design/#/ https://www.npmjs.com/search?q=macros
因为使用物料肯定有那么有个前提就是你得清楚自己需要什么以及什么才是你需要的嘛，这可能是另外一个项目基于 block 的描述文件去生成一个物料查询平台

[yutingzhao1991]

@tolerance-go 后面应该会有基于 antd pro 的一个官方物料市场，当然社区也都可以基于这套体系来搭建自己的物料市场。

[devmsg]

repost