@wlydfe/pro-ui 0.2.20 → 0.2.21

package/docs/components/QA.md

@@ -0,0 +1,195 @@
+# 常见问题
+
+## 组件 TypeScript 类型不兼容或错误 ？
+
+借用[Ant Design Pro](https://pro.ant.design/zh-CN/docs/type-script/#ts-ignore)官网的一句话:
+
+`TypeScript 毕竟是一个标注语言，在需要使用 any 的时候不必吝于使用 any，在遇到【动态性比较强的代码】时，不妨使用 as unknown as XXX, 可以节省很多时间。`
+
+`@ts-ignore` `@vue-ignore`
+
+有些时候类型错误是组件的，但是看起来非常难受。会一直编译报错，这里就可以使用 `@ts-ignore` 来暂时忽略它，在模板中还可以使用`@vue-ignore`
+
+> \*.vue
+
+```html
+<template>
+  <!-- @vue-ignore -->
+  <!-- 报错的组件 -->
+</template>
+
+<script lang="ts" setup>
+  // @ts-ignore
+  // 报错的行
+</script>
+```
+
+## 表格的 columns 使用 ref 定义类型报错
+
+[详见 issues/195](https://github.com/plus-pro-components/plus-pro-components/issues/195)
+
+```ts
+import type { Ref } from 'vue'
+import type { PlusColumn } from 'plus-pro-components'
+
+//  const columns = ref<PlusColumn[]>([])   类型替换为下面的写法
+const columns: Ref<PlusColumn[]> = ref([])
+```
+
+## 是否兼容element-plus@2.6.0 ？
+
+是， [详见 issues/79](https://github.com/plus-pro-components/plus-pro-components/issues/79)，[详见 issues/105](https://github.com/plus-pro-components/plus-pro-components/issues/105)
+
+## 按钮，placeholder，标题文本显示异常？
+
+![详见](/i18n-error.png)
+
+![详见](/i18n-error2.png)
+
+问题原因：未配置 `plus-pro-components` 的国际化。
+
+解决方案：[配置国际化](/guide/i18n.html)
+
+## 国际化配置了不起效果？
+
+[详见](/guide/i18n.html#国际化不起效果)
+
+## 表单字段改变后怎么根据改变字段的值通过接口获取另一个字段的 options?
+
+[详见 issues/99](https://github.com/plus-pro-components/plus-pro-components/issues/99)
+
+## PlusTable 和 PlusForm 复用 PlusColumn 问题？
+
+[详见 issues/94](https://github.com/plus-pro-components/plus-pro-components/issues/94)
+
+## 单个组件的事件在哪里配置?
+
+[参考](/components/attrs.html)
+
+## PlusTable 表格操作栏如何居中显示?
+
+小于<el-tag>v0.1.7</el-tag>
+
+```css
+.plus-table .plus-table-action-bar .cell {
+  justify-content: center;
+}
+```
+
+大于等于<el-tag>v0.1.7</el-tag>
+
+```html
+<PlusTable :action-bar="{ actionBarTableColumnProps: { align: 'center' } }" />
+```
+
+## PlusTable 表格操作栏如何做权限控制?
+
+小于<el-tag>v0.1.7</el-tag>
+
+可使用 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow) 中的 `show` 字段控制。 [示例](/components/table.html#自定义操作栏)
+
+大于等于<el-tag>v0.1.7</el-tag>
+
+可使用 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow) 中的 `directives`指令字段控制。[示例](/components/table.html#权限控制)
+
+## 搜索表单如何改变重置、搜索按钮的顺序?
+
+[参考 flex 布局 order ](https://www.w3school.com.cn/tiy/t.asp?f=cssref_order)
+
+[详见 issues/54](https://github.com/plus-pro-components/plus-pro-components/issues/54)
+
+```css
+.plus-search__button__wrapper .el-button {
+  order: 2;
+}
+
+.plus-search__button__wrapper .el-button--primary {
+  order: 1;
+  margin-left: 0;
+  margin-right: 20px;
+}
+
+.plus-search__button__wrapper .el-link {
+  order: 3;
+}
+```
+
+## PlusForm 里面的表单元素，想单独占一行，但是宽度是`{colProps: {span: 8}}` 怎么配置？
+
+```ts
+import type { PlusColumn } from 'plus-pro-components'
+
+const columns: PlusColumn[] = [
+  {
+    label: 'test',
+    prop: 'test',
+    colProps: {
+      span: 8, // 实际宽度是 33.3%
+      // @ts-ignore
+      style: { marginRight: '67%' }
+    }
+  }
+]
+```
+
+## 表单中的某项如何添加 ref 获取实例，使用实例的方法？
+
+```vue {15,50-52}
+<template>
+  <el-card>
+    <PlusForm v-model="state" label-width="140px" :columns="columns" />
+  </el-card>
+</template>
+
+<script lang="ts" setup>
+import { ref, watch } from 'vue'
+import type { PlusColumn, FieldValues } from 'plus-pro-components'
+
+const state = ref<FieldValues>({
+  'tree-select': ''
+})
+
+const treeSelectInstance = ref()
+
+watch(treeSelectInstance, val => {
+  console.log(val, 'val')
+})
+
+const cascaderOptions = [
+  {
+    value: '0',
+    label: '陕西',
+    children: [
+      {
+        value: '0-0',
+        label: '西安',
+        children: [
+          {
+            value: '0-0-0',
+            label: '新城区'
+          },
+          {
+            value: '0-0-1',
+            label: '高新区'
+          }
+        ]
+      }
+    ]
+  }
+]
+
+const columns: PlusColumn[] = [
+  {
+    label: 'tree-select',
+    prop: 'tree-select',
+    valueType: 'tree-select',
+    fieldProps: {
+      ref: e => {
+        treeSelectInstance.value = e
+      },
+      data: cascaderOptions
+    }
+  }
+]
+</script>
+```

package/docs/components/attrs.md

@@ -0,0 +1,257 @@
+# 事件和样式透传
+
+## 事件透传
+
+### vue3 的事件透传原则如下
+
+**`以 on 开头，并跟着大写字母的 props 会被当作事件监听器。`**
+
+**比如，onClick 与模板中的 @click 等价，onVisibleChange 与模板中的 @visible-change 等价**
+
+参考 vue 官方文档 **[透传 Attributes](https://cn.vuejs.org/guide/components/attrs.html)**
+
+参考 vue 官方文档 **[渲染函数 & JSX](https://cn.vuejs.org/guide/extras/render-function.html)**
+
+### `PlusProComponents` 组件的事件透传
+
+具备以下条件的都支持事件透传
+
+- **[columns](/components/config.html) 配置中的`*Props`字段**
+
+- **其他组件中的`*Props`字段**
+
+- **文档中说明这个字段是组件的 props 的字段**
+
+### `fieldProps` 事件示例
+
+[columns](/components/config.html) 配置中的`fieldProps`字段表示的是 传递给具体表单项和表格显示的配置，如 el-input，el-select，el-tag，el-image 的 props ，同时还支持事件透传
+
+```js
+const columns = [
+  {
+    label: '状态',
+    prop: 'status',
+    // 对应的element-plus 的组件el-select
+    valueType: 'select',
+    options: [],
+    fieldProps: {
+      // https://element-plus.org/zh-CN/component/select.html#select-events
+      // el-select 的事件 `change`，对应的配置就是 `onChange`
+      onChange: () => {
+        console.log('onChange')
+      },
+      // el-select 的事件 `visible-change`，对应的配置就是 `onVisibleChange`
+      onVisibleChange: () => {
+        console.log('visibleChange')
+      },
+      // el-select 的事件 `remove-tag`，对应的配置就是 `onRemoveTag`
+      onRemoveTag: () => {
+        console.log('onRemoveTag')
+      }
+    }
+  },
+  {
+    label: '名称',
+    prop: 'name',
+    // 对应的element-plus 的组件el-input
+    valueType: 'input',
+    fieldProps: {
+      // https://element-plus.org/zh-CN/component/input.html#input-events
+      // el-input 的事件 `blur`，对应的配置就是 `onBlur`
+      onBlur: () => {
+        console.log('onBlur')
+      },
+      // el-input 的事件 `focus`，对应的配置就是 `onFocus`
+      onFocus: () => {
+        console.log('onFocus')
+      },
+      // el-input 的事件 `change`，对应的配置就是 `onChange`
+      onChange: () => {
+        console.log('onChange')
+      },
+      // el-input 的事件 `input`，对应的配置就是 `onInput`
+      onInput: () => {
+        console.log('onInput')
+      },
+      // el-input 的事件 `clear`，对应的配置就是 `onClear`
+      onClear: () => {
+        console.log('onClear')
+      }
+    }
+  }
+]
+```
+
+### 需要 `事件修饰符` 和 `按键修饰符`的事件写法示例
+
+[参考 Vue 官方写法](https://cn.vuejs.org/guide/extras/render-function.html#event-modifiers)
+
+- 对于 `.passive`、`.capture` 和 `.once` 事件修饰符，可以使用驼峰写法将他们拼接在事件名后面。
+
+  示例
+
+  ```ts
+  import type { PlusColumn } from 'plus-pro-components'
+
+  const columns: PlusColumn[] = [
+    {
+      label: '文本',
+      prop: 'text',
+      valueType: 'text',
+      fieldProps: {
+        onClickCapture() {
+          /* 捕捉模式中的监听器 */
+        },
+        onKeyupOnce() {
+          /* 只触发一次 */
+        },
+        onMouseoverOnceCapture() {
+          /* 单次 + 捕捉 */
+        }
+      }
+    }
+  ]
+  ```
+
+- 其他`修饰符`写法，需要使用`withKeys`、[withModifiers](https://cn.vuejs.org/api/render-function.html#withmodifiers)
+
+  以`fieldProps`为例，支持点击阻止事件冒泡, 按下 Enter 键提交搜索等。
+
+  ```html
+  <template>
+    <div @click="handleClickWrapper">
+      <PlusSearch v-model="state" :columns="columns" :has-unfold="false" @search="handleSearch" />
+    </div>
+  </template>
+
+  <script lang="ts" setup>
+    import { ref, withKeys, withModifiers } from 'vue'
+    import type { PlusColumn } from 'plus-pro-components'
+
+    const state = ref({
+      text: '我是一段有想法的文本',
+      name: '名字',
+      time: new Date().toString()
+    })
+
+    const columns: PlusColumn[] = [
+      {
+        label: '文本',
+        prop: 'text',
+        valueType: 'text',
+        fieldProps: {
+          style: {
+            cursor: 'pointer',
+            userSelect: 'none'
+          },
+          // 阻止事件冒泡，只有点击自己时触发
+          onClick: withModifiers(() => {
+            console.log('点击文本了')
+          }, ['stop', 'self'])
+        }
+      },
+      // valueType 没有的情况下，默认为'input'，对应el-input组件
+      {
+        label: '名称1',
+        prop: 'name',
+        fieldProps: {
+          // 当前输入框聚焦状态，按下Enter 键提交搜索
+          onKeyup: withKeys(() => {
+            handleSearch()
+          }, ['enter'])
+        }
+      },
+      /**
+       * 凑数的
+       * 当一个表单中只有一个单行文本输入字段时， 浏览器应当将在此字段中按下 Enter （回车键）的行为视为提交表单的请求。
+       */
+      {
+        label: '时间',
+        prop: 'time',
+        valueType: 'date-picker'
+      }
+    ]
+    const handleSearch = () => {
+      console.log('Enter 键触发了')
+    }
+    const handleClickWrapper = () => {
+      console.log('点击第一个文本时，不会被事件冒泡机制触发，点击其他地方正常触发')
+    }
+  </script>
+  ```
+
+[vue 官方建议使用 withModifiers，为什么使用 withKeys？](https://github.com/vuejs/babel-plugin-jsx/issues/269)
+
+### PlusLayout 子组件事件写法示例
+
+[PlusLayout](/components/layout.html) 的 `sidebarProps` 和`headerProps`表示的就是子组件的 props。
+
+如 [PlusSidebar ](/components/sidebar.html) 的事件 `toggleCollapse`和 [PlusHeader ](/components/header.html)的事件`clickDropdownItem`。
+
+示例：
+
+> 模板中
+
+```html
+<PlusLayout
+  :sidebarProps="{ onToggleCollapse: handleToggleCollapse }"
+  :headerProps="{ onClickDropdownItem: handleClickDropdownItem}"
+/>
+```
+
+> setup 中
+
+```ts
+const handleClickDropdownItem = (dropdownItem: { label: string; value: string }) => {
+  console.log(dropdownItem)
+}
+
+const handleToggleCollapse = (collapse: boolean) => {
+  console.log(collapse)
+}
+```
+
+### 其他\*Props 和高级组件事件写法参考上面示例
+
+## 样式透传
+
+支持事件透传的一般都支持样式透传
+
+### `fieldProps` 样式透传示例
+
+```js
+const columns = [
+  {
+    label: '状态',
+    prop: 'status',
+    // 对应的element-plus 的组件el-select
+    valueType: 'select',
+    options: [],
+    fieldProps: {
+      // 对应的 el-select 的样式
+      style: {
+        width: '100%'
+      }
+    }
+  }
+]
+```
+
+### `colProps` 样式透传示例
+
+```js
+const columns = [
+  {
+    label: '名称',
+    prop: 'name',
+    colProps: {
+      // 对应的 el-col 的样式
+      style: {
+        marginLeft: '10px'
+      }
+    }
+  }
+]
+```
+
+### 其他参考上面示例

package/docs/components/breadcrumb.md

@@ -0,0 +1,80 @@
+# Breadcrumb 面包屑
+
+## 简介
+
+PlusBreadcrumb 展示面包屑。
+
+## 基础用法
+
+:::demo
+
+breadcrumb/basic
+
+:::
+
+## 不显示某一级
+
+路由信息的`meta` 中添加 `hideInBreadcrumb: true`即可。 路由信息配置[ PlusRouteRecordRaw](/components/type.html#plusrouterecordraw)
+
+:::demo
+
+breadcrumb/hidden
+
+:::
+
+## 自定义 (renderTitle)
+
+:::warning 注意
+**render 函数的优先级高于插槽**
+:::
+
+:::demo
+
+breadcrumb/render
+
+:::
+
+## 自定义 (jsx/tsx)
+
+:::demo
+
+breadcrumb/tsx
+
+:::
+
+## 自定义 (插槽)
+
+:::warning 注意
+**插槽优先级低于 render**
+:::
+
+:::demo
+
+breadcrumb/slots
+
+:::
+
+## Breadcrumb API
+
+## Breadcrumb Attributes
+
+| 名称          | 说明                                           | 类型                                                                                    | 默认值  | 是否必须 |
+| ------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- | ------- | -------- |
+| `routes`      | 面包屑的路由信息，不传默认取的是 route.matched | `array` [PlusRouteRecordRaw[]](/components/type.html#plusrouterecordraw)                |         | 否       |
+| `replace`     | 面包屑跳转时是否是替换模式                     | `boolean`                                                                               | `false` | 否       |
+| `renderTitle` | 自定义 面包屑显示                              | `function` <docs-tip content='(route:PlusRouteRecordRaw) => VNode / string'></docs-tip> |         | 否       |
+| ...           | ...                                            | ...                                                                                     | ...     | ...      |
+
+:::tip 提示
+**`...`表示同时支持所有 [el-breadcrumb](https://element-plus.org/zh-CN/component/breadcrumb.html#breadcrumb-attributes) Attributes**
+:::
+
+## Breadcrumb Slots
+
+| 插槽名                  | 说明              | 作用域插槽参数                                                       |
+| ----------------------- | ----------------- | -------------------------------------------------------------------- |
+| `breadcrumb-item-title` | 自定义 面包屑显示 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) |
+
+:::warning 注意
+**render 函数的优先级高于插槽**
+:::

package/docs/components/check-card-group.md

@@ -0,0 +1,129 @@
+# CheckCardGroup 多选卡片组
+
+## 简介
+
+PlusCheckCardGroup 集成 [PlusCheckCard](/components/check-card.html) 实现多选功能。
+
+## 单选用法
+
+:::demo
+
+check-card-group/basic
+
+:::
+
+## 多选用法
+
+配置 multiple 可实现多选。
+
+:::demo
+
+check-card-group/multiple
+
+:::
+
+## 不同尺寸
+
+配置 size 控制整体尺寸大小，当前可选 large，default，small，不同尺寸仅宽度不同。 options 中的 size 优先级更高。
+
+:::demo
+
+check-card-group/size
+
+:::
+
+## 禁用
+
+配置 disabled 控制整体 禁用， options 中的 disabled 优先级更高。
+
+:::demo
+
+check-card-group/disabled
+
+:::
+
+## 自定义 (render)
+
+:::warning 注意
+**render 函数的优先级高于插槽**
+:::
+
+:::demo
+
+check-card-group/custom
+
+:::
+
+## 自定义 (jsx/tsx)
+
+:::demo
+
+check-card-group/tsx
+
+:::
+
+## 自定义 (插槽)
+
+:::warning 注意
+**插槽优先级低于 render**
+:::
+
+插槽支持**整体**配置 和 **单项（个性化）** 配置，**整体插槽**会改变每一项，**单项（个性化）插槽**可以单独定制其中的某一项。
+
+**单项插槽**说明：`CheckCardGroup` 组件会自动根据配置项的 `value` 生成对应的插槽，例如下面的配置项，则会自动生成以下名称叫做 [ **title-`0`** ]，[ **avatar-`0`**] ， [ **description-`0`**]，[ **title-`1`** ]，[ **avatar-`1`**] 和 [ **description-`1`**] 的插槽，插槽的生成规则就是 固定 key 值 [ **title-** ]，[ **avatar-** ] ，[ **description-** ] 然后加上 配置项的 `value`。`extra` 插槽 也是同样的逻辑 [ **extra-** ] + `value` 。
+
+```ts
+const options = [
+  {
+    title: 'title0',
+    value: '0',
+    description: 'description0',
+    avatar: 'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg'
+  },
+  {
+    title: 'title1',
+    value: '1',
+    description: 'description1',
+    avatar: 'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg'
+  }
+]
+```
+
+:::demo
+
+check-card-group/slot
+
+:::
+
+## CheckCardGroup API
+
+## CheckCardGroup Attributes
+
+| 名称                    | 说明                                                                                                                                        | 类型                                                                                              | 默认值  | 是否必须 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------- | -------- |
+| `model-value / v-model` | 绑定值                                                                                                                                      | `string/number` / (`array` <docs-tip content='string[]/number[]/(number /string)[]'></docs-tip> ) |         | 否       |
+| `options`               | 数据数组，支持 [PlusCheckCard](/components/check-card.html#checkcard-attributes) 的所有 `props` (`modelValue` 除外)，数组中`value` 为必选项 | `array` <docs-tip content=' (PlusCheckCardProps & { value: string / number })[]'></docs-tip>      |         | 否       |
+| `size`                  | 尺寸                                                                                                                                        | `string` <docs-tip content='"default" / "small" / "large"'></docs-tip>                            |         | 否       |
+| `disabled`              | 禁用                                                                                                                                        | `boolean`                                                                                         | `false` | 否       |
+| `multiple`              | 多选，当值为`true` 时 `v-model` 的类型是对应的数组。                                                                                        | `boolean`                                                                                         | `false` | 否       |
+
+## CheckCardGroup Events
+
+| 名称     | 说明           | 类型                                                                                                         |
+| -------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
+| `change` | 点击卡片时触发 | `function` <docs-tip content='(checked: (string/number)[]) => void'></docs-tip>                              |
+| `extra`  | 点击操作栏触发 | `function` <docs-tip content='(option: PlusCheckCardProps & { value: string / number }) => void'></docs-tip> |
+
+## CheckCardGroup Slots
+
+| 插槽名             | 说明          | 作用域插槽参数                                                      |
+| ------------------ | ------------- | ------------------------------------------------------------------- |
+| `avatar`(-\*)      | 自定义 头像   | `object` <docs-tip content='{avatar,title,description}'></docs-tip> |
+| `title`(-\*)       | 自定义 标题   | `object` <docs-tip content='{avatar,title,description}'></docs-tip> |
+| `description`(-\*) | 自定义 描述   | `object` <docs-tip content='{avatar,title,description}'></docs-tip> |
+| `extra`(-\*)       | 自定义 操作栏 | `object` <docs-tip content='{avatar,title,description}'></docs-tip> |
+
+:::tip 提示
+
+带 `-*` 表示是单项（个性化）插槽，组件会自动根据配置项的 value 生成对应的插槽
+:::