docs: update docs and diff scripts

xiaodemen · Justineo · commit aa9ad39d7935 · 2022-03-25T11:43:39.000+08:00
Change-Id: I4cb7236ee045f81f3bf54725ba8f1c7d840bbf04
diff --git a/one/build/diff-api.js b/one/build/diff-api.js
@@ -14,16 +14,35 @@ import {
   SyntaxKind,
   forEachChild
 } from 'typescript'
+import ignore from './diff-ignore'
 
 const docPath = join(__dirname, '../docs/components')
 const typesDir = join(resolveLib('veui'), 'types')
 const Ls = createLs()
 
+function getIgnoreComponents () {
+  return Object.keys(ignore)
+    .filter(key => ignore[key] === '*')
+}
+
+function isIgnore (componentName, apiType, apiName) {
+  let container = ignore['*'][apiType]
+  if (container && container.includes(apiName)) {
+    return true
+  }
+
+  container = ignore[componentName]
+  return container
+    ? container === '*' || (container[apiType] || []).includes(apiName)
+    : false
+}
+
 function getApiFromDocs () {
+  const ignoreComponents = getIgnoreComponents()
   return readdirSync(docPath)
     .reduce((acc, name) => {
       const match = name.match(/(.+)\.md$/)
-      if (match) {
+      if (match && !ignoreComponents.includes(match[1])) {
         const absPath = join(docPath, name)
         acc[match[1]] = getComponentApiFromDoc(absPath)
       }
@@ -68,7 +87,10 @@ function getComponentApiFromDoc (docFile) {
     })
     .toArray()
     .reduce((acc, name) => {
-      acc[name] = null
+      // 过滤掉 <value> 这种事件
+      if (!name.match(/^<[-\w]+>$/)) {
+        acc[name] = null
+      }
       return acc
     }, {})
 
@@ -96,24 +118,24 @@ function getApiFromVeuiTypes () {
 
 function visit (saveApi, node) {
   if (node.kind === SyntaxKind.ExportAssignment) {
-    const ck = Ls.getProgram().getTypeChecker()
-    const sym = ck.getSymbolAtLocation(node.expression) // node.expression: id to Autocomplete
-    const type = ck.getTypeAtLocation(sym.declarations[0].name)
+    const checker = Ls.getProgram().getTypeChecker()
+    const sym = checker.getSymbolAtLocation(node.expression) // node.expression: id to Autocomplete
+    const type = checker.getTypeAtLocation(sym.declarations[0].name)
     const rt = type.getConstructSignatures()[0].getReturnType()
     const all = rt.getProperties()
     const props = all.find(sy => sy.escapedName === '$props')
     let result = {}
 
-    result.props = ck
+    result.props = checker
       .getTypeOfSymbolAtLocation(props, node)
       .getProperties()
       .reduce((acc, sy) => {
-        acc[sy.escapedName] = ck.typeToString(ck.getTypeOfSymbolAtLocation(sy, node))
+        acc[sy.escapedName] = checker.typeToString(checker.getTypeOfSymbolAtLocation(sy, node))
         return acc
       }, {})
 
     const emits = all.find(sy => sy.escapedName === '$emit')
-    const emitsType = ck.getTypeOfSymbolAtLocation(emits, node)
+    const emitsType = checker.getTypeOfSymbolAtLocation(emits, node)
     const emitsCollection = emitsType.isIntersection()
       ? emitsType.types
       : [emitsType]
@@ -123,25 +145,27 @@ function visit (saveApi, node) {
         return ty.getCallSignatures()[0]
           .getParameters()
           .reduce((acc, argSy) => {
-            const argType = ck.getTypeOfSymbolAtLocation(argSy, node)
+            const argType = checker.getTypeOfSymbolAtLocation(argSy, node)
 
-            const tstr = ck.typeToString(argType)
+            const tstr = checker.typeToString(argType)
             const matched = /^"([^"]+)"$/.exec(tstr)
             acc[argSy.escapedName] = matched ? matched[1] : tstr
             return acc
           }, {})
       })
       .reduce((acc, { event, args }) => {
-        acc[event] = args
+        if (event !== 'string') {
+          acc[event] = args
+        }
         return acc
       }, {})
 
     const slots = all.find(sy => sy.escapedName === '$scopedSlots')
-    const slotsType = ck
+    const slotsType = checker
       .getTypeOfSymbolAtLocation(slots, node)
       .getProperties()
       .reduce((acc, symbol) => {
-        acc[symbol.escapedName] = getScope(symbol, node, ck)
+        acc[symbol.escapedName] = getScope(symbol, node, checker)
         return acc
       }, {})
 
@@ -305,6 +329,16 @@ function writeDiffFile () {
   const tsApi = getApiFromVeuiTypes()
   const docApi = getApiFromDocs()
   const diff = diffApi(tsApi, docApi)
+    .map(item => {
+      item.props = item.props.filter(({ key }) => !isIgnore(item.component, 'props', key))
+      item.emits = item.emits.filter(({ key }) => !isIgnore(item.component, 'emits', key))
+      item.slots = item.slots.filter(({ key }) => !isIgnore(item.component, 'slots', key))
+      return item
+    })
+    .filter(({ props, slots, emits }) => {
+      return !!props.length || !!slots.length || !!emits.length
+    })
+
   writeFileSync(join(__dirname, 'diff.json'), JSON.stringify(diff, null, '  '), 'utf8')
 }
 
diff --git a/one/build/diff-ignore.js b/one/build/diff-ignore.js
@@ -0,0 +1,40 @@
+export default {
+  schedule: '*',
+  'region-picker': '*',
+  embedded: '*',
+  '*': {
+    props: [
+      'ui',
+      'name',
+      'invalid',
+      'overlayClass',
+      'overlayStyle',
+      'overlayPriority',
+      'keyField'
+    ]
+  },
+  button: {
+    props: ['value']
+  },
+  cascader: {
+    emits: ['toggle']
+  },
+  checkbox: {
+    props: ['model']
+  },
+  radio: {
+    props: ['model']
+  },
+  switch: {
+    props: ['model']
+  },
+  drawer: {
+    props: ['inline']
+  },
+  select: {
+    props: ['max'] // 脚本没识别出来，先忽略
+  },
+  link: {
+    props: ['replace']
+  }
+}
diff --git a/one/docs/components/carousel.md b/one/docs/components/carousel.md
@@ -67,11 +67,13 @@
 | ``vertical`` | `boolean=` | `false` | 是否是纵向布局的轮播。 |
 | ``indicator-align`` | `'start' | 'end'` | `start` | 用于支持指示器的相对于布局方向的位置。 |
 | ``indicator-position`` | `'outside' | 'inside'` | `inside` | 用于支持指示器显示在轮播容器的内部/外部。 |
+| ``controls`` | `boolean` | `false` | 是否显示切换按钮。 |
 | ``controls-position`` | `'outside' | 'inside'` | `inside` | 用于支持切换按钮相对于布局方向的位置。 |
 | ``slide-aspect-ratio`` | `number= | '${number}/${number}'` | - | 指定不同轮播项类型的默认配置。 |
 | ``options`` | `Object=` | `{ video: { muted: true, autoplay: true, controls: true, loop: true } }` | 用于指定每个轮播项的纵横比。 |
 | ``slides-per-view`` | `number=` | `1` | 指定同时显示多少个轮播项。 |
 | ``slides-per-group`` | `number=` | `1` | 指定每次前后切换的一组包含多少个轮播项。 |
+| ``lazy`` | `boolean= | { preload: number }` | `false` | [^lazy] |
 
 ^^^datasource
 轮播图数据源，项目类型为：`{src, alt, label, type}`。
@@ -117,6 +119,18 @@
 +++
 ^^^
 
+^^^lazy
+指定是否懒加载轮播资源。
+
++++详情
+| 名称 | 描述 |
+| -- | -- | -- |
+| `false` | 不懒加载资源。 |
+| `true` | 预加载当前展示项目的前后 1 个资源。 |
+| `{ preload: number }` | 预加载当前展示项目的前后指定数量个资源。 |
++++
+^^^
+
 ### 插槽
 
 | 名称 | 描述 |
diff --git a/one/docs/components/cascader.md b/one/docs/components/cascader.md
@@ -66,6 +66,8 @@
 | ``column-width`` | `number | string` | - | [^column-width] |
 | ``show-select-all`` | `boolean` | `false` | 在多选模式下是否有全选按钮。 |
 | ``value-display`` | `'complete' | 'simple'` | `'simple'` | [^value-display] |
+| ``merge-checked`` | `string=` | `keep-all` | [^merge-checked] |
+| ``include-indeterminate`` | `boolean` | `false` | 是否将半选状态的节点加入已选项。[`datasource`](#props-datasource) 节点中的非叶子节点若有部分子孙节点被选中，则为半选状态。 |
 | ``disabled`` | `boolean=` | `false` | 是否为禁用状态。 |
 | ``readonly`` | `boolean=` | `false` | 是否为只读状态。 |
 | ``overlay-class`` | `string | Array | Object=` | - | 参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props-overlay-class) 属性。 |
@@ -155,6 +157,19 @@
 +++
 ^^^
 
+^^^merge-checked
+
+选中值的合并策略。当某个节点下的所有子节点都被选中时，可以选择只保留父节点、只保留子节点或都保留。
+
++++枚举值
+| 值 | 描述 |
+| -- | -- |
+| `keep-all` | 父子节点都会在选中值中。 |
+| `upwards` | 尽可能往祖先方向合并选中值。 |
+| `downwards` | 尽可能往后代方向合并选中值。 |
++++
+^^^
+
 ### 插槽
 
 | 名称 | 描述 |
diff --git a/one/docs/components/column.md b/one/docs/components/column.md
@@ -21,6 +21,7 @@
 | ``align`` | `string=` | - | 内容对齐方式，支持 `left` / `center` / `right`。 |
 | ``span`` | `function(number): Object=` | | [^span] |
 | ``desc`` | `string` | - | 表头描述。 |
+| ``fixed`` | `boolean | 'left' | 'right'` | `false` | 该列是否固定，`'left'` 表示固定在左侧，`'right'` 表示在右侧。 |
 | ``filter-value`` | `*` | - | [^filter-value] |
 | ``filter-multiple`` | `boolean=` | `false` | 内置筛选是否为多选。 |
 | ``filter-options`` | `Array<Object>` | - | 筛选选项列表，项目的类型为 `{label, value, options, disabled, ...}`，可参考 [`Select`](./select) 组件的 [`options`](./select#props-options) 属性。 |
@@ -122,3 +123,9 @@
 | `close` | `function(): void` | 关闭筛选浮层。 |
 +++
 ^^^
+
+### 事件
+
+| 名称 | 描述 |
+| -- | -- |
+| ``filterchange`` | 修改该列过滤器时触发。回调参数为 `(value)`。`value` 为过滤器的当前值。 |
diff --git a/one/docs/components/drawer.md b/one/docs/components/drawer.md
@@ -31,7 +31,6 @@
 | ``open`` | `boolean` | `false` | [^open] |
 | ``closable`` | `boolean` | `true` | 是否显示关闭按钮。 |
 | ``outside-closable`` | `boolean` | `false` | 点击抽屉外部时是否关闭抽屉。 |
-| ``draggable`` | `boolean` | `false` | 是否可拖拽。 |
 | ``escapable`` | `boolean` | `false` | 按下 <kbd>esc</kbd> 键是否可以关闭抽屉。仅在 `closable` 为 `true` 时生效。 |
 | ``footless`` | `boolean` | `false` | 是否不显示默认的底部操作栏。 |
 | ``loading`` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 |
diff --git a/one/docs/components/dropdown.md b/one/docs/components/dropdown.md
@@ -101,8 +101,6 @@
 | 名称 | 描述 |
 | -- | -- |
 | ``default`` | 选项列表的内容。在没有指定 [`options`](#props-options) 属性时，可以用来直接内联 `Option` 或 `OptionGroup`。 |
-| ``before`` | 选项列表前的内容。无默认内容。 |
-| ``after`` | 选项列表后的内容。无默认内容。 |
 | ``label`` | [^slot-label] |
 | ``group-label`` | [^slot-group-label] |
 | ``option-label`` | [^slot-option-label] |
diff --git a/one/docs/components/filter-panel.md b/one/docs/components/filter-panel.md
@@ -15,6 +15,7 @@
 | ``filter`` | `function=` | 见描述 | [^filter] |
 | ``search-on-input`` | `boolean=` | `true` | 是否在输入的时候触发搜索。 |
 | ``placeholder`` | `string=` | - | 搜索框的占位符。 |
+| ``title`` | `string=` | - | 过滤面板的标题。 |
 
 ^^^filter
 搜索过滤函数，签名为 `function(keyword, item, index, datasource): boolean`。返回值为 `false` 的项目将被从结果中过滤掉。
diff --git a/one/docs/components/icon.md b/one/docs/components/icon.md
@@ -16,15 +16,7 @@ VEUI 的 `Icon` 组件目前兼容 [Vue-Awesome](https://github.com/Justineo/vue
 | -- | -- | -- | -- |
 | ``name`` | `string | Object` | - | 图标名称或其组件定义。 |
 | ``label`` | `string` | - | 图标的文字说明，对辅助设备可见。当不设置时，图标对辅助设备隐藏。 |
-| ``scale`` | `number` | - | 图标尺寸倍数。不设置时相当于 `1`。 |
 | ``spin`` | `boolean` | `false` | 是否保持旋转状态。 |
-| ``pulse`` | `boolean` | `false` | 是否保持步进旋转状态。 |
-| ``inverse`` | `boolean` | `false` | 是否翻转颜色（用白色绘制，用于深色背景）。 |
-| ``flip`` | `string` | - | 是否翻转，可选值为 `'horizontal'` / `'vertical'`，分别表示水平翻转与垂直翻转。 |
-
-:::warning
-当 [`name`](#props-name) 属性使用组件定义时，仅支持 [`spin`](#props-spin) 属性。
-:::
 
 ### 插槽
 
diff --git a/one/docs/components/tree.md b/one/docs/components/tree.md
@@ -30,6 +30,7 @@
 | ``selectable`` | `boolean` | `false` | 点击整个节点区域时是否选中该节点。 |
 | ``selected`` | `string` | - | [^selected] |
 | ``merge-checked`` | `string` | `keep-all` | [^merge-checked] |
+| ``include-indeterminate`` | `boolean` | `false` | 是否将半选状态的节点加入已选项。[`datasource`](#props-datasource) 节点中的非叶子节点若有部分子孙节点被选中，则为半选状态。 |
 
 ^^^ui
 预设样式。
