docs: add api dev docs link and custom plugin dev docs; #!zh 增加后端 api 文档链接和自定义组件开发文档

ly525
1 parent 44f695ca
Showing 9 changed files with 460 additions and 12 deletions
docs/.vuepress/config.js
docs/zh/plugin-development/README.md
docs/zh/plugin-development/cli-params.md
docs/zh/plugin-development/how-it-works/custom-editor-multiple-props.md
docs/zh/plugin-development/how-it-works/custom-editor-single-prop.md
docs/zh/plugin-development/how-it-works/simple-prop.md
docs/zh/plugin-development/plugin-default-inject-props.md
docs/zh/plugin-development/quick-start.md
docs/zh/plugin-development/reference.md
@@ -36,6 +36,7 @@ module.exports = {
           // { text: 'API', link: '/api/' },
           { text: 'Website', link: 'https://h5.luban-h5.com' },
           { text: 'Changelog', link: 'https://github.com/ly525/luban-h5/releases' },
+          { text: 'Api Docs', link: 'https://h5.luban-h5.com/documentation/' },
         ],
         sidebar: {
           '/': [
@@ -59,10 +60,17 @@ module.exports = {
               ],
             },
             {
-              collapsable: true,
-              title: '🔌 Local plugins',
+              collapsable: false,
+              title: '🔌Plugins Development',
               children: [
-                '/en/plugin-development/quick-start',
+                '/zh/plugin-development/',
+                '/zh/plugin-development/how-it-works/simple-prop',
+                '/zh/plugin-development/how-it-works/custom-editor-single-prop',
+                '/zh/plugin-development/how-it-works/custom-editor-multiple-props',
+                '/zh/plugin-development/quick-start',
+                '/zh/plugin-development/cli-params',
+                '/zh/plugin-development/plugin-default-inject-props',
+                '/zh/plugin-development/reference',
               ],
             },
             {
@@ -86,6 +94,7 @@ module.exports = {
           // { text: '插件', link: '/zh/plugin/' },
           { text: '首页', link: 'https://h5.luban-h5.com' },
           { text: '发布日志', link: 'https://github.com/ly525/luban-h5/releases' },
+          { text: '后端API文档', link: 'https://h5.luban-h5.com/documentation/' },
         ],
         sidebar: {
           '/': [
@@ -109,10 +118,17 @@ module.exports = {
               ],
             },
             {
-              collapsable: true,
-              title: '🔌 Local plugins',
+              collapsable: false,
+              title: '🔌插件/自定义组件开发(Alpha)',
               children: [
+                '/zh/plugin-development/',
+                '/zh/plugin-development/how-it-works/simple-prop',
+                '/zh/plugin-development/how-it-works/custom-editor-single-prop',
+                '/zh/plugin-development/how-it-works/custom-editor-multiple-props',
                 '/zh/plugin-development/quick-start',
+                '/zh/plugin-development/cli-params',
+                '/zh/plugin-development/plugin-default-inject-props',
+                '/zh/plugin-development/reference',
               ],
             },
             {
+# 目录
+> 说明，自定义组件目前处于 Alpha 版本，持续迭代中，API 可能会发生重大变化。
+> 建议到 Beta 版本再使用
+
+- [原理篇：简单属性编辑器](how-it-works/simple-prop.md)
+- [原理篇：单属性自定义编辑器](how-it-works/custom-editor-single-prop.md)
+- [原理篇：多属性自定义编辑器](how-it-works/custom-editor-multiple-props.md)
+- [脚手架：快速上手](quick-start.md)
+- [脚手架：命令行交互说明](cli-params.md)
+- [组件：默认属性注入](plugin-default-inject-props.md)
+- [参考资料](reference.md)
 \ No newline at end of file
+# 脚手架-命令行参数说明
+
+## 命令参数说明
+1. `组件的名称(发布到npm)`：***输入组件名称***
+   * 默认为 `test`，这个名字最后会作为：component name
+   * 将在luban-h5的编辑器中，通过 `yarn add component-name` 的形式引入
+
+2. `icon`: ***输入icon***
+  > ![image](https://user-images.githubusercontent.com/12668546/69070298-daac0200-0a62-11ea-9543-9199f6040545.png)
+
+
+  * 访问 [Font Awesome 4.7 版本](https://fontawesome.com/v4.7.0/icons/)
+
+  * 按照下图的方法，选择一个 icon, 在命令行对话中，输入即可
+  > ![image](https://user-images.githubusercontent.com/12668546/69069617-c3204980-0a61-11ea-8239-7f7bf660297d.png)
+
+
+  ```js
+  export default {
+    // 在 https://fontawesome.com/v4.7.0/icons/ 中寻找对应的 icon，填入 icon 字段即可
+    icon: 'address-book',
+    name: 'luban-h5-address',
+  }
+  ```
+
+3. `是否有命名空间(@scope)`：***Yes or No***
+   * 作为组织或者企业开发组件，可以选择 `Yes`，在下一步，填写 `npm scope`
+
+4. `scope(命名空间<理解为企业/组织名称>)`: ***输入scope名称***
+   * 将企业/组织的组件放在 `@组织名` 下, 便于管理
+   * 举例1：
+       * LubanH5 的官方组件库，都放在了`@luban-h5`这个 scope 下。
+       * 以按钮组件为例，通过 `yarn add @luban-h5/lbc-button`，即可引入官方按钮组件了
+       * 用户一看到 `@luban-h5` 这个，就知道是由 LubanH5 官方提供的组件库
+   * 举例2：
+       * 你的企业/组织名称是 `abc`，你在开发 `upload` 上传组件，那么就可以选择：
+
+       ```bash
+       组件的名称(发布到npm) ：upload
+       是否有命名空间(@scope)：Yes
+       scope：abc
+
+       通过 `npm publish --access public` 发布到 npm
+       通过`npm install @abc/upload` 或 `yarn add @abc/uplaod`， 即可引入到`鲁班编辑器`中作为`自定义组件`使用
+       ```
+
+
+## 相关概念
+[npm-scope 官网文档](https://docs.npmjs.com/misc/scope)
 \ No newline at end of file
+# 原理篇:多属性自定义编辑器
+> 自定义组件/插件/Plugin 原理概览
+
+## 举例 [鲁班H5 轮播图组件](https://github.com/luban-h5-components/lbp-slide)
+- 这个组件本质上就是一个 vue 组件
+- 其本质是对 [Vant组件库的轮播组件](https://youzan.github.io/vant/#/zh-CN/swipe) 的简单封装
+- [核心代码](https://github.com/luban-h5-components/lbp-slide/blob/master/src/component/entry.vue)
+  - 可以看出来，核心代码其实非常简单，和大家平时写轮播图，或者调用第三方组件库的轮播图的方式几乎没有区别，基本上是配置一些 props，比如轮播间隔时间、轮播图列表等
+  - 接下来我们来讲一下不同的地方在哪里🧐
+
+## 自定义组件和常规组件的不同之处(影响多个属性)
+以[如下这段代码](https://github.com/luban-h5-components/lbp-slide/blob/master/src/component/entry.vue#L57-L67)为例，相信写 `vue` 或者 `react` 的同学，应该会比较熟悉
+
+配置 轮播组件的 items，也就是轮播的选项信息
+```js
+props: {
+  items: {
+    type: Array,
+    default: () => [
+      { value: 'https://img.yzcdn.cn/vant/apple-1.jpg' },
+      { value: 'https://img.yzcdn.cn/vant/apple-2.jpg' }
+    ],
+    // 主要区别应该是这里
+    editor: {
+      custom: true
+    }
+  }
+}
+```
+
+- 这里和我们平时写的组件是有些区别的，我们添加了这些信息
+```js
+editor: {
+  custom: true
+}
+```
+- 其中`custom: true` 表示在编辑器的右侧面板，采用`自定义属性编辑器`来配置`自定义组件`的相关属性
+
+- 在这里可以理解为：采用`自定义属性编辑器`来配置`轮播组件`的`items`属性
+
+- 那么，它和上面的 按钮组件的 `color.editor` 有什么区别呢？为何这里不采用一个第三方组件呢？
+
+- 答案：因为有时候，有些操作会影响多个属性值（联动）
+
+- 以轮播图组件的实际场景为例，我们来解释下什么叫：`有些操作会影响多个属性值`。毕竟这句话猛的一听，有点像教科书，晦涩难懂，咱还是说说实际业务场景吧
+
+> 有图有真相：
+> ![image](https://user-images.githubusercontent.com/12668546/73135735-b7b05680-4080-11ea-9d54-02760c9a13d3.png)
+
+- 按照图中的说法，如果我们点击了【减号】按钮，其实就会影响到两个属性：`activeIndex` 和 `items`，因此如果写了一个和上面的颜色选择器一样的组件，放在 activeIndex 或 items 任意一方中都是不太合适的，因为这个算是二者共有的；
+    - 轮播图 props 主要代码如下：[代码链接](https://github.com/luban-h5-components/lbp-slide/blob/master/src/component/entry.vue#L50-L67)：
+
+    ```js
+    props: {
+      activeIndex: {
+        type: Number,
+        default: 0,
+        editor: {
+          custom: true
+        }
+      },
+      items: {
+        type: Array,
+        default: () => [
+          { value: 'https://img.yzcdn.cn/vant/apple-1.jpg' },
+          { value: 'https://img.yzcdn.cn/vant/apple-2.jpg' }
+        ],
+        editor: {
+          custom: true
+        }
+      }
+    }
+    ```
+
+- 如何解决呢：
+  - 还记得我们上面讲过的，将按钮 放置到 中间画布上的操作吗？
+
+    ***鲁班会自动遍历`按钮组件` 的 `props`，构造一个包含了组件基本属性和其默认值的配置对象：`pluginProps`***
+
+  - 我们可以写一个组件，比如叫 `slideEditor` (轮播编辑器，叫啥随你，最好有相关性，清晰易懂即可，最好加注释)
+  - 我们要解决的问题是，点击一个按钮，会修改多个属性的值，多个属性的值和其值存在哪里呢？其实就在 `pluginProps` 中
+  - 我们把 `pluginProps` 作为属性传入到 `slideEditor`(也就说将轮播图组件的所有 props和其值 都传入到 slideEditor 中)，这样就可以在 slideEditor 中更新这个 pluginProps 了，换句话说，所有的 props和值都给你了，你可以改多个 props 的值了
+  - show me the code，让我们看下 slideEditor 是如何实现的吧，主要代码如下：[完整代码链接](https://github.com/luban-h5-components/lbp-slide/blob/master/src/component/editor.vue)
+  ```vue
+    <!--
+      轮播组件属性自定义编辑器（增强编辑器）
+      文档：https://github.com/luban-h5/vue-cli-plugin-lbhc/wiki
+    -->
+    <template>
+      <div>
+        <a-pagination
+          :current="current"
+          @change="handleSelectPage"
+          size="small"
+          :total="innerItems.length"
+          :defaultPageSize="1"
+          :itemRender="itemRender"
+        />
+        <lbs-image-gallery
+          style="margin: 16px 0"
+          :value="currentItem.value"
+          @change="handleSelectImage"
+        />
+      </div>
+    </template>
+
+    <script>
+    export default {
+      props: {
+        /**
+         * 通过 new Vue.component('plugin-name').$optioins.props 收集组件的属性
+         * 作为 Object，传递给 props editor，从而从过属性自定义编辑器 来更新属性值
+         */
+        pluginProps: {
+          type: Object,
+          default: () => ({
+            items: [],
+            activeIndex: 0
+          })
+        }
+      },
+      methods: {
+        itemRender (current, type, originalElement) {
+          // 减号按钮
+          if (type === 'prev') {
+            return <a-button style={{ marginRight: '8px' }} size="small" icon="minus" onClick={() => this.minus(current)} disabled={this.innerItems.length === 1}></a-button>
+          } else if (type === 'next') {
+            return <a-button style={{ marginLeft: '8px' }} size="small" icon="plus" onClick={this.add}></a-button>
+          }
+          return originalElement
+        },
+        // 点击减号的 callback：items.splice 和 activeIndex--
+        minus (index) {
+          if (this.innerItems.length === 1) return
+          this.pluginProps.items.splice(index, 1)
+          this.pluginProps.activeIndex = Math.max(index - 1, 0)
+        }
+      }
+    }
+    </script>
+  ```
+
+大概的原理到这里就差不多，这也是鲁班H5的自定义组件和其编辑器的核心原理了
+
+下一章来讲讲，如何利用鲁班H5 官网提供的`自定义组件-脚手架`来`快速开发`自定义组件
+# 原理篇:单属性自定义编辑器
+> 自定义组件/插件/Plugin 原理概览
+
+通过`自定义属性编辑器`来配置组件的某些属性的`复杂编辑需求`
+
+举个例子：图片的 imgSrc 属性，采用自定义编辑器的方法如下，[图片演示](https://user-images.githubusercontent.com/12668546/69001396-6a916500-0918-11ea-8f39-5e27a688d2fe.png)
+
+```js
+props: {
+  imgSrc: {
+    type: String,
+    defualt: '',
+    editor: {
+      custom: true
+      // 如果写了 custom: true，则会采用 editor.vue 或者 editor.js 来配置组件的相关属性
+      // 自定义组件的加载目前在 mini-editor/panel/props.js 的 loadCustomEditorForPlugin 方法中加载并注册
+      // 这样，就可以通过自定义属性编辑器来配置组件的某些复杂属性了
+      // 图片演示：https://user-images.githubusercontent.com/12668546/69001396-6a916500-0918-11ea-8f39-5e27a688d2fe.png
+    }
+  }
+}
+```
+
+- 1. 从上面来看，其实我们自定义的这个图片选择器，只影响到了 imgSrc 这一个属性
+- 2. 其实可以把它抽象出来作为一个组件(比如叫做 `luban-support-image-gallery`(鲁班辅助支撑组件-图片库))
+- 3. 发布到 npm 上，作为全局组件引入即可
+
+简单改造下 imgSrc 的属性配置：
+```js
+props: {
+  imgSrc: {
+    type: String,
+    defualt: '',
+    editor: {
+      type: 'luban-support-image-gallery'
+    }
+  }
+}
+```
+# 原理篇:简单属性编辑器
+> 自定义组件/插件/Plugin 原理概览
+
+## [鲁班H5 按钮组件](https://github.com/luban-h5-components/lbc-button)
+- 这个组件本质上就是一个 vue 组件
+- [核心代码](https://github.com/luban-h5-components/lbc-button/blob/master/src/component/entry.js)
+  - 可以看出来，核心代码其实非常简单，和大家平时写按钮组件差不多，基本上是配置一些 props，比如颜色、字体、内容、背景色、前景色、border 等
+  - 以 color 为例：
+  ![image](https://user-images.githubusercontent.com/12668546/73135438-f8a66c00-407c-11ea-9f7c-1b110ea3b2b3.png)
+
+    ```js
+    props: {
+      color: {
+        type: String,
+        // 注意，根据 MDN 文档，颜色选择器的 value 只能是：# + 6个16进制字符串
+        // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color#Value
+        // The value of an <input> element of type color is always a DOMString which contains a 7-character string specifying an RGB color in hexadecimal format.
+        default: '#000000',
+        editor: {
+          type: 'el-color-picker',
+          label: '文字颜色',
+          // !#zh 为编辑组件指定 prop
+          prop: {
+            size: 'mini',
+            showAlpha: true
+          },
+          require: true
+        }
+      },
+    }
+    ```
+      - 可以看到相对于平时我们写的 Vue 或者 React 组件，这里的 color 的 prop 多了一个 key: `editor`
+      - 这个 `color.editor` 就是 颜色的`属性编辑器`了，因为鲁班默认集成了 element-ui 的颜色选择器组件，因此我们可以直接使用 `'el-color-picker'` 来作为颜色属性的自定义编辑器
+      - 当然，鲁班也集成了 ant-design-vue 的全部组件，但因为 ant-design-vue 的颜色选择器目前功能上没有 element-ui 的颜色选择器强大（不支持透明度），因此我们选择了 element-ui 的颜色选择器
+
+
+  - 在把`按钮` 从左侧`拖拽放置`到 `编辑器`中间的画布上的时候，鲁班会自动执行如下代码：
+    - 遍历`按钮组件`的`props`
+    - 构造 pluginProps 对象，作为画布中按钮元素的描述信息（也是数据库中存储的信息）
+        ```js
+        // init prop of plugin
+        getDefaultPluginProps (props) {
+          const pluginProps = {
+            uuid: this.uuid // uuid 用于在组件树中定位组件
+          }
+          Object.keys(props).forEach(key => {
+            const defaultValue = props[key].default
+            pluginProps[key] = typeof defaultValue === 'function' ? defaultValue() : defaultValue
+          })
+          return pluginProps
+        }
+        ```
+
+    - 得到的结果大致如下，也就代表着，按钮在画布上的颜色、文字、边框、对齐、字体等信息如下
+      ```js
+      pluginProps = {
+        "uuid": 1580038843434,
+        "text": "按钮",
+        "vertical": false,
+        "backgroundColor": "rgba(255, 255, 255, 0.2)",
+        "color": "#000000",
+        "fontSize": 14,
+        "lineHeight": 1,
+        "borderWidth": 0,
+        "borderRadius": 0,
+        "borderColor": "#ced4da",
+        "textAlign": "center"
+      }
+      ```
+
+## 简单属性编辑器小结
+如果组件的某些属性比较简单，比如文本、数字，则可以使用 [ant-design-vue](https://www.antdv.com/docs/vue/introduce-cn/) 组件来配置组件的属性
+
+举个例子：图片的 imgSrc 配置，[图片演示](https://user-images.githubusercontent.com/12668546/69001390-42096b00-0918-11ea-85b4-0ec868e44769.png)
+
+```js
+props: {
+  imgSrc: {
+    type: String,
+    defualt: '',
+    editor: {
+      type: 'a-input'
+      // 调用 ant-design-vue 的 input(输入框) 组件来配置 imgSrc，直接复制粘贴图片的链接即可
+      // 图片演示：https://user-images.githubusercontent.com/12668546/69001390-42096b00-0918-11ea-85b4-0ec868e44769.png
+
+      // 这样比较简单，但是有时候，用户可能希望编辑图片的时候，可以自己上传 或 从图片库中选择图片
+      // 图片演示：https://user-images.githubusercontent.com/12668546/69001396-6a916500-0918-11ea-8f39-5e27a688d2fe.png
+      // 这时候，简单的 input(输入框) 就无法满足需求了，这时候给组件属性配置自定义编辑器就有了用武之地了，具体请往下看。
+    }
+  }
+}
+```
+# 组件默认属性
+> 鲁班向自定义组件 默认注入了一些属性，便于开发
+
+### editorMode 编辑器当前模式
+  *  preview: 预览模式
+  *  edit:   编辑模式
+
+```js
+props: {
+  editorMode: {
+    type: String,
+    default: 'edit'
+  },
+}
+```
+
+
+```js
+/**
+  * #!zh: 编辑器当前模式：
+  *  preview: 预览模式
+  *  edit:   编辑模式
+  *
+  *  通常用在轮播图、单选、多选、提交按钮、视频
+  *  因为他们在编辑模式和预览模式下有不同的表现
+  *
+  *  举例：
+  * ================================================================================================================================
+  * | 组件名称         |  编辑模式表现               |    预览模式表现                |
+  * ================================================================================================================================
+  * | 轮播图           |   正在编辑的图片            |      轮播图                   |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  * | 提交按钮         |   仅可点击, 但不会提交表单    |      可点击, 且可以提交表单     |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  * | 视频            |   视频占位 icon             |      可播放的视频              |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  *
+  *
+  *
+  * #!en: current mode for editor
+  *  preview: preview mode
+  *  edit:    edit mode
+  *
+  *  commonly used for carousel, checkbox, radio, form submit button、video etc...
+  *  Because they have different behaviour in edit mode and preview mode.
+  *
+  *  Examples:
+  * ================================================================================================================================
+  * |  Component            |    Edit Mode Behaviour                           |  Preview Mode Behaviour               |
+  * ================================================================================================================================
+  * |  carousel             |    editing image                                 |  carousel                             |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  * |  form submit button   |    only clickable, but will not submit the form  |  clickable, can submit the form       |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  * |  video                |    video placeholder icon                        |  playable video                       |
+  * --------------------------------------------------------------------------------------------------------------------------------
+  *
+  */
+```
 \ No newline at end of file
 # 快速开始
-TODO
+> 以下内容与 [vue-cli-plugin-lbhc README](https://github.com/luban-h5/vue-cli-plugin-lbhc) 相同
  
-### 如何进行插件开发
+> vue-cli-plugin-lbhc 全称为：vue-cli-plugin-luban-h5-component
  
-我现在的认知里面，做成插件的模式，还是需要clone 下来 debug 插件的实际效果的
-不过可以改进插件的开发流程，让插件作者尽量低成本的开发，只要注重插件本身的逻辑就可以了
+## 安装
  
-它山之石：Vuepress、Grafana
+### 使用preset自动安装插件
+```
+vue create --preset luban-h5/vue-cli-plugin-lbhc my-luban-component-demo
+```
  
  
----
+### 目录结构
  
-<Vssue issueId="10" />
 \ No newline at end of file
+```bash
+mini-editor 模拟鲁班H5的核心编辑器功能
+component   你要编写组件的目录
+  index.js  组件入口
+  editor.js 组件的编辑面板配置
+
+```
+
+
+### 开发流程
+
+```bash
+vue create --preset luban-h5/vue-cli-plugin-lbhc lbc-demo
+cd lbc-demo
+yarn serve
+
+# 构建、发布个人组件
+yarn build
+npm login
+npm publish
+
+
+# 构建发布 scope 组件
+yarn build
+npm login
+npm publish --access publish
+```
+# 参考资料
+
+1. Vue Cli3+
+2. Grafana
+3. Figma
+
+---
+
+<Vssue issueId="10" />
 \ No newline at end of file