From aa9ad39d7935136a09e8c5649f1d7dd6b7d34a06 Mon Sep 17 00:00:00 2001 From: xiaodemen Date: Wed, 23 Mar 2022 17:21:16 +0800 Subject: [PATCH] docs: update docs and diff scripts Change-Id: I4cb7236ee045f81f3bf54725ba8f1c7d840bbf04 --- one/build/diff-api.js | 60 ++++++++++++++++++++++------- one/build/diff-ignore.js | 40 +++++++++++++++++++ one/docs/components/carousel.md | 14 +++++++ one/docs/components/cascader.md | 15 ++++++++ one/docs/components/column.md | 7 ++++ one/docs/components/drawer.md | 1 - one/docs/components/dropdown.md | 2 - one/docs/components/filter-panel.md | 1 + one/docs/components/icon.md | 8 ---- one/docs/components/tree.md | 1 + 10 files changed, 125 insertions(+), 24 deletions(-) create mode 100644 one/build/diff-ignore.js diff --git a/one/build/diff-api.js b/one/build/diff-api.js index 98a30e8..e653263 100644 --- 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 + // 过滤掉 这种事件 + 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 new file mode 100644 index 0000000..d0a2e5d --- /dev/null +++ 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 index 3dd35e7..de260a9 100644 --- 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 index 5418bb7..fe9cccc 100644 --- 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 index 5e1488b..8e3b510 100644 --- 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` | - | 筛选选项列表，项目的类型为 `{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 index bf38e2c..9ff8d7d 100644 --- 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` | 按下 esc 键是否可以关闭抽屉。仅在 `closable` 为 `true` 时生效。 | | ``footless`` | `boolean` | `false` | 是否不显示默认的底部操作栏。 | | ``loading`` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 | diff --git a/one/docs/components/dropdown.md b/one/docs/components/dropdown.md index df39d58..e0d0c44 100644 --- 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 index a6d2058..49e67c2 100644 --- 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 index f675178..9a740c0 100644 --- 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 index d2ec0f9..04e69e1 100644 --- 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 预设样式。