--- url: /ecosystem/eslint-config.md --- # @plus-pro-components/eslint-config [![@plus-pro-components/eslint-config version badge](https://img.shields.io/npm/v/@plus-pro-components/eslint-config.svg?style=flat-square)](https://www.npmjs.org/package/@plus-pro-components/eslint-config) ## 简介 `@plus-pro-components/eslint-config` 是 `plus-pro-components` 内置的 eslint 配置集合，集成了常用的 `vue`、`ts`、`import`插件，为快速配置 eslint 提供保障。 ## 使用 * 安装 ```sh pnpm i @plus-pro-components/eslint-config ``` * 配置 ```js {4} // .eslintrc.js module.exports = { root: true, extends: ['@plus-pro-components/eslint-config'] } ``` --- --- url: /ecosystem/resolver.md --- # @plus-pro-components/resolver [![@plus-pro-components/resolver version badge](https://img.shields.io/npm/v/@plus-pro-components/resolver.svg?style=flat-square)](https://www.npmjs.org/package/@plus-pro-components/resolver) ## 简介 `@plus-pro-components/resolver` 是[plus-pro-components](https://plus-pro-components.com/)为 [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components) 提供的官方解析器，可以按需自动导入`plus-pro-components`的组件及其样式文件。 ## 使用 * 安装 ```sh pnpm i @plus-pro-components/resolver ``` * 配置 ```ts {5,11} // vite.config.ts import { defineConfig } from 'vite' import Components from 'unplugin-vue-components/vite' import { PlusProComponentsResolver } from '@plus-pro-components/resolver' export default defineConfig({ // ... plugins: [ Components({ resolvers: [PlusProComponentsResolver({ importStyle: 'css' })] }) ] }) ``` ## 配置参数说明 | 参数名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------- | ------------------------ | ----------------------------------------------------- | ------- | -------- | | `ssr` | 是否是 ssr | `boolean` | `false` | 否 | | `importStyle` | 导入的样式文件类型 | `string` | `css` | 否 | | `exclude` | 不需要加载的组件名称正则 | `RegExp` | | 否 | | `noStylesComponents` | 不需要加载样式的组件名称 | `array` | | 否 | --- --- url: /api/utils.md --- # @plus-pro-components/utils [![@plus-pro-components/utils version badge](https://img.shields.io/npm/v/@plus-pro-components/utils.svg?style=flat-square)](https://www.npmjs.org/package/@plus-pro-components/utils) ## 简介 `@plus-pro-components/utils` 提供了 web 开发常用的工具库，它具有以下特点： * 和`plus-pro-components`解耦，独立的 npm 包，可选安装。 * 安装后结合 plus-pro-components 使用会非常方便。 * 它提供了基于 ES Module 的开箱即用的 [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) 功能，无需担心引入会导致打包体积增大。 * 使用 TypeScript 编写，提供 d.ts，使用起来安全便捷。 有新的工具需求 👉 欢迎 [issues](https://github.com/plus-pro-components/plus-pro-components/issues) ## 独立安装 ::: code-group ```sh [pnpm] pnpm install @plus-pro-components/utils ``` ```sh [npm] npm install @plus-pro-components/utils --save ``` ```sh [yarn] yarn add @plus-pro-components/utils ``` ::: ## 使用示例 ```ts import { formatMoney } from '@plus-pro-components/utils' formatMoney('100') // ￥100.00 ``` --- --- url: /guide/installation.md --- # 安装 ## 环境支持 | [![edge](https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png)](http://godban.github.io/browsers-support-badges/) | [![Edge](https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png)](http://godban.github.io/browsers-support-badges/) | [![chrome](https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png)](http://godban.github.io/browsers-support-badges/) | [![safari](https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png)](http://godban.github.io/browsers-support-badges/) | | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Edge | last 2 versions | last 2 versions | last 2 versions | ### 版本 `PlusProComponents` 目前处于功能稳定阶段。 [![ElementPlus version badge](https://img.shields.io/npm/v/plus-pro-components.svg?style=flat-square)](https://www.npmjs.org/package/plus-pro-components) ## 使用包管理器 推荐 ::: warning 注意 `plus-pro-components`大于等于 `0.0.11` 版本，`element-plus`不再作为`plus-pro-components`的依赖，需要单独安装。 ::: **建议您使用包管理器 ([pnpm](https://pnpm.io/)推荐 ， [yarn](https://classic.yarnpkg.com/lang/en/)，[npm](https://www.npmjs.com/)) 安装 plus-pro-components**。 ::: code-group ```sh [pnpm] pnpm install plus-pro-components ``` ```sh [yarn] yarn add plus-pro-components ``` ```sh [npm] npm install plus-pro-components --save ``` ::: ## 浏览器直接引入 直接通过浏览器的 HTML 标签导入 plus-pro-components，然后就可以使用全局变量 `PlusProComponents` 了。 根据不同的 CDN 提供商有不同的引入方式， 我们在这里以[unpkg](https://unpkg.com) 和 [jsDelivr](https://jsdelivr.com) 举例。 你也可以使用其它的 CDN 供应商。 ### unpkg ```html{10,12} ``` ### jsDelivr ```html{10,12} ``` ::: warning 注意 默认使用最新版本，使用时建议加上版本号 如使用`0.0.1`版本，防止因版本导致应用出现问题。 ::: --- --- url: /guide/dark-mode.md --- # 暗黑模式 支持 element-plus 的暗黑模式，点击本网站右上角 **切换暗黑模式** 按钮，去[组件](/components/layout.html)页面即可体验。 [element-plus 暗黑模式文档](https://element-plus.org/zh-CN/guide/dark-mode.html)。 --- --- url: /guide/upgrade.md --- # 版本升级 本记录只记录影响较大变更，对于一般[新功能、性能提升和问题修复](/guide/changelog.html)不在此记录。 ## 从 v0.1.18 升级到 v0.1.19 * [PlusLayout](/components/layout.html) 布局样式发生变化，注意适配。 ## 从 v0.1.14 升级到 v0.1.15 * [PlusSearch](/components/search.html#search-attributes) 新增了折叠动画 默认开启，不需要的话，设置 `collapseTransition` 为 `false`即可。 ```html ``` * [PlusColumn](/components/config.html) 中对 `options` 新增了 `optionsMap`,可以对 `options` 中的字段显示进行自定义。 [参考](/components/config.html) * [PlusColumn](/components/config.html) 中 `tooltip` 新增了计算属性支持。 [参考](/components/config.html) ## 从 v0.1.13 升级到 v0.1.14 * [PlusPage](/components/page.html) Exposes 变更 [参考](/components/page.html#page-exposes) `handleRest` 方法已废弃（未来会在 v0.2.0 版本中移除），请使用 `handleReset `代替。 [参考](/components/page.html#page-exposes) ## 从 v0.1.8 升级到 v0.1.11 * 提升了组件 TS 类型兼容性 在 v0.1.8 版本的基础上，提升了组件的 TS 类型兼容性，不存在的类型不再会提示类型错误。 ## 从 v0.1.7 升级到 v0.1.8 * [PlusColumn](/components/config.html) 中的 `formItemProps` 中的 `labelWidth` 开始生效，原来[PlusColumn](/components/config.html) 中的配置 `labelWidth` 不再生效。 ```ts import type { PlusColumn } from 'plus-pro-components' const columns: PlusColumn[] = [ { label: 'test', prop: 'test', labelWidth: '100px', // [!code --] formItemProps: { labelWidth: '100px' // [!code ++] } } ] ``` * 组件 TS 类型更加严格 组件的 TS 类型更加严格了，提示性更好了，兼容性降低了，不影响功能，但是会提示类型错误。 ## 从 v0.1.4 升级到 v0.1.6 ### [PlusDrawerForm](/components/drawer-form.html) * 废弃了 `drawer` props，el-drawer 的 props 直接在 [PlusDrawerForm](/components/drawer-form.html) 上写。 ## v0.1.0 ### 更加友好 * 重构了 [PlusFormItem](/components/form-item.html) 和重 [PlusDisplay](/components/display-item.html) 组件，对新功能扩展更加友好。 * 重构了 d.ts 生成工具，ts 提示由原来的 `80%` 提升至 `100%`，对用户使用更加友好。 ### 体积更小 * 整包体积由原来的 `39.5MB` 优化至 `9.5MB`，体积减少了 `76%`。 * CSS 体积由原来的 `17.7kB` 优化至 `12.8KB`，体积减少了 `28%`。 ### 更高的单元测试覆盖率 * 单元测试覆盖率由原来的 `90%` 提升至 `92.5%`。 ## 从 v0.0.9 升级到 v0.0.10 ### PlusDrawerForm 抽屉表单 事件修改 * [PlusDrawerForm](/components/drawer-form.html#drawerform-events) 的事件`submit` 已废弃，请使用`confirm` 代替。[ 参考 DrawerForm-events](/components/drawer-form.html#drawerform-events) ## 从 v0.0.7 升级到 v0.0.8 ### 国际化文件导入方式修改 * 导入文件报错 ```sh ERROR failed to resolve import "plus-pro-components/locale/zh-cn.mjs" ERROR failed to resolve import "plus-pro-components/locale/en.mjs" ``` * 解决方案 ```js import plusZhCn from 'plus-pro-components/locale/zh-cn.mjs' // [!code --] import plusZhCn from 'plus-pro-components/locale/zh-cn' // [!code ++] import plusEn from 'plus-pro-components/locale/en.mjs' // [!code --] import plusEn from 'plus-pro-components/locale/en' // [!code ++] ``` 或者 ```js import plusZhCn from 'plus-pro-components/locale/zh-cn.mjs' // [!code --] import plusZhCn from 'plus-pro-components/es/locale/lang/zh-cn' // [!code ++] import plusEn from 'plus-pro-components/locale/en.mjs' // [!code --] import plusEn from 'plus-pro-components/es/locale/lang/en' // [!code ++] ``` ## 从 v0.0.4 升级到 v0.0.5 ### PlusSearch 搜索组件 * 搜索按钮现在默认靠右，要恢复以前的顺序排布可使用以下代码 ```css .plus-search .plus-search__button__wrapper.el-form-item { flex: none; } ``` ## 从 v0.0.3 升级到 v0.0.4 ### PlusFormItem 表单单项组件 * 表单单项组件 移除了 `valueType === 'date-picker'`时，`el-date-picker` 组件的默认属性 `format` 和`value-format`，原来的默认值都为 `YYYY-MM-DD HH:mm:ss`。 * 受影响的组件 [PlusForm](/components/form.html)， [PlusDialogForm](/components/dialog-form.html)，[PlusDrawerForm ](/components/drawer-form.html)， [PlusStepsForm ](/components/steps-form.html)，[PlusSearch ](/components/search.html)，[PlusDisplayItem ](/components/display-item.html)，[PlusTable ](/components/table.html)，[PlusPage ](/components/page.html) ## 从 v0.0.2 升级到 v0.0.3 ### 高级组件通用配置 columns * `headerFilter`参数已废弃，请使用 `disabledHeaderFilter`代替。[ 参考 columns](/components/config.html) --- --- url: /guide/dev.md --- # 本地开发指南 ## 开发环境 | 类型 | 名称 | 版本 | | ------------- | ----------------- | -------------- | | 操作系统 | Windows 11 专业版 | 22000.1098 | | 开发工具 | Microsoft VS Code | 1.79.0 | | 调试工具 | Google Chrome | 104.0.5112.102 | | 代码版本控制 | git | 2.37.0 | | 语言环境 | node | 18.19.0 | | 包管理器 | npm | 8.19.2 | | 包管理器 | yarn | 1.22.19 | | 包管理器 | pnpm | 8.15.7 | | node 版本管理 | nvm | 1.1.7 | | npm 源管理 | nrm | 1.2.5 | ## 项目结构 ```sh ├── CHANGELOG.md #changelog文件 ├── commitlint.config.js #commitlint配置 ├── docs #文档所在目录 | ├── .vitepress #vitepress配置 | ├── components #组件文档 | ├── examples #组件文档对应的vue示例 | ├── deploy.sh #文档部署脚本 | ├── guide #快速开始文档 | ├── index.md #文档首页 | ├── package.json | ├── public | └── utils ├── global.d.ts #全局组件ts提示 ├── LICENSE #LICENSE 文件 ├── package.json ├── packages #包文件夹 | ├── components #主组件 | ├── constants #固定变量 | ├── eslint-config #eslint配置独立 | ├── hooks #hooks | ├── locale #国际化 | ├── play #组件实时预览 | ├── plus-pro-components #主包入口 | ├── utils #工具 | ├── theme-chalk #样式 | └── types #公共TS类型 ├── pnpm-lock.yaml ├── pnpm-workspace.yaml #工作空间配置 ├── README.md #项目介绍 ├── scripts #脚本 | ├── build #主包打包 | ├── changelog #changelog | ├── create-component #新增组件 | ├── release #整包release | ├── utils #公共打包工具 | ├── commit.sh #代码提交 | └── publish.sh #整包发布 ├── tsconfig.base.json #tsconfig配置 ├── tsconfig.json ├── tsconfig.node.json ├── tsconfig.vitest.json ├── tsconfig.web.json ├── typings #全局d.ts | └── env.d.ts └── vitest.config.ts #vitest配置 ``` ## 克隆仓库 ```sh git clone https://github.com/plus-pro-components/plus-pro-components.git ``` 如果 GitHub 克隆速度较慢，你也可以直接克隆 plus-pro-components 在 gitee 上的[镜像仓库](https://gitee.com/plus-pro-components/plus-pro-components.git)，同步可能会存在时差。 ```bash git clone https://gitee.com/plus-pro-components/plus-pro-components.git ``` ## 启动项目 ```sh pnpm i ``` ## 文档网站预览 ```sh pnpm docs:dev ``` ## 本地开发 ```sh pnpm dev ``` ## 添加新的组件步骤 例如现在需要新增一个新的组件 组件名叫 `table` 对应的 vue 组件名称叫 `PlusTable`（所有组件名字以`Plus` 开头，组件的基本代码全部会自动生成。） ### 1. 组件创建 * 执行创建组件脚本 ```sh pnpm run new table ``` * 确定 ``` Confirm create table component? yes ``` * 此时 packages/components/table 文件夹已经生成并且有了如下目录 ```sh ├── index.ts #主文件 ├── src | └── index.vue #组件实际代码 ├── style | ├── index.ts #组件按需加载 scss 样式，包含自身样式和外部样式 | └── css.ts #组件按需加载 css 样式，包含自身样式和外部样式 └── __tests__ └── table.test.tsx #单元测试代码 主要测试组件中的 props、event、slots、样式、CSS class 名、生命周期钩子，和其他相关的问题。 ``` 然后添加组件实际代码和对应的单元测试 * 导出组件 packages/components/index.ts 新增 ```ts export * from './table' ``` * 在 packages/plus-pro-components/component.ts 添加新增的组件 `PlusTable` ```js import { PlusTable } from '@plus-pro-components/components/table' const plugins: Component[] = [PlusDialog, PlusPagination, PlusTable] ``` * 在 `global.d.ts` 添加类型 ```ts{3} declare module '@vue/runtime-core' { export interface GlobalComponents { PlusTable: typeof import('plus-pro-components')['PlusTable'] } } ``` ### 2. 预览组件 * 执行下面的命令 ```sh pnpm run dev ``` * 打开 packages/play/src/views/table.vue(文件自动生成) 里面新增如下代码 ```html ``` * 打开终端地址即可预览组件 ### 3. 组件的测试 单元测试 写完之后 执行 ```sh pnpm run test ``` 查看测试覆盖率 ```sh pnpm run test:coverage ``` ### 4. 文档的添加 * 执行打包命令 ```sh pnpm run build ``` * 在 docs/components 文件下， 新建文件 table.md 内容写法参考之前的 * 在 docs/文件夹下执行 `pnpm run start` 后的地址即可预览已打包的本地组件 * 在 docs/文件夹下执行 `pnpm run debug` 后的地址即可实时预览正在开发的本地组件 ## 代码提交 ```sh pnpm run commit # 全部提交 ``` ::: tip 提示 **如果需要分次提交** 可以先执行 `git add ./x/x `，再执行`pnpm run gitcz`，最后执行 `git push origin dev`(或者其他分支)。 ::: ## 打包组件 ```sh pnpm run build ``` --- --- url: /components/QA.md --- # 常见问题 ## 组件 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 ``` ## 表格的 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([]) 类型替换为下面的写法 const columns: Ref = 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 表格操作栏如何居中显示? 小于v0.1.7 ```css .plus-table .plus-table-action-bar .cell { justify-content: center; } ``` 大于等于v0.1.7 ```html ``` ## PlusTable 表格操作栏如何做权限控制? 小于v0.1.7 可使用 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow) 中的 `show` 字段控制。 [示例](/components/table.html#自定义操作栏) 大于等于v0.1.7 可使用 [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} ``` ## PlusTable 设置了 adaptive 属性，在搜索栏没有展开表格内容是可以自适应的 展开后表格高度还是之前的怎么办？ 在 [PlusSearch](/components/search.html#search-events) 的事件 [collapse](/components/search.html#search-events) 中主动触发 [PlusTable](/components/table.html) 的 `resize` 方法 ```vue {2,127-132} ``` --- --- url: /guide/changelog.md --- # 更新日志 在这个页面上，你只能看到我们最近更新的 30 条 更新日志。 ## 版本发布策略 | 发布者 | 阶段 | 发布策略 | 备注 | | ---------------------- | ------------------------------------- | -------- | ------------------------------------------------------------------- | | PlusProComponents 团队 | 快速开发迭代阶段 | 每周 | 关键的 bug 修复将需要热修复，所以实际发布版本可能每周超过 1 次 | | PlusProComponents 团队 | 功能稳定阶段 current | 1-6 个月 | 关键的 bug 修复将需要热修复，所以实际发布版本可能每 6 个月超过 1 次 | ## 推荐版本 推荐选择[release](https://github.com/plus-pro-components/plus-pro-components/releases)版本，功能稳定。参考[release 版本列表](https://github.com/plus-pro-components/plus-pro-components/releases)。 --- --- url: /guide/contribution.md --- # 贡献指南 ### 介绍 感谢您使用 PlusProComponents。 以下是关于向 PlusProComponents 提交反馈或代码的指南。在向 PlusProComponents 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下内容。 ### Issue 规范 * 遇到问题时，请先确认这个问题是否已经在 issue 中有记录或者已被修复。 * 提 issue 时，请用简短的语言描述遇到的问题，并添加出现问题时的**环境** 和复现步骤，必要时需提供可复现问题最小代码仓库。 #### 环境包含 * `浏览器` 版本 * `操作系统` 版本 * `node` 版本 * `vite`/ `webpack` / `Rollup` / `Vue CLI` 构建工具版本， 是否使用 `CDN` * `vue` 版本 * `element-plus` 版本 * `plus-pro-components` 版本 ## 参与开发 ### [参考本地开发](/guide/dev.html) ### 代码规范 在编写代码时，请注意： * 确保代码可以通过仓库的 ESLint 校验。 * 确保代码格式是规范的，使用 prettier 进行代码格式化。 * 确保没有使用超出兼容性范围的 API. ## 提交 Pull Request ### 参考指南 如果你是第一次在 GitHub 上提 Pull Request ，可以阅读下面这两篇文章来学习： * [第一次参与开源](https://github.com/firstcontributions/first-contributions/blob/main/translations/README.zh-cn.md) * [如何优雅地在 GitHub 上贡献代码](https://segmentfault.com/a/1190000000736629) ### Pull Request 规范 在提交 Pull Request 时，请注意： * 保持你的 PR 足够小，一个 PR 只解决单个问题或添加单个功能。 * 当新增组件或者修改原有组件时，记得增加或者修改对应的单元测试，保证代码的稳定。 * 在 PR 中请添加合适的描述，并关联相关的 Issue。 ### Pull Request 流程 1. fork 主仓库，如果已经 fork 过，请同步主仓库的最新代码。 2. 基于 fork 后仓库的 dev 分支新建一个分支，比如 `feature/docs`。 3. 在新分支上进行开发，开发完成后，提 Pull Request 到主仓库的 dev 分支。 4. Pull Request 会在 Review 通过后被合并到主仓库。 5. 等待 PlusProComponents 发布新版本，一般是每周一次。 ### Pull Request 标题格式 Pull Request 的标题应该遵循以下格式： ```bash type(ComponentName?)：commit message ``` 示例： * docs: fix typo in quickstart * build: optimize build speed * fix(component\[form-item]): incorrect style * feat(component\[table]): add color prop 可选的类型： * feat * fix * build * docs * test * style * ci * refactor * perf * chore * revert ### 同步最新代码 提 Pull Request 前，请依照下面的流程同步主仓库的最新代码： ```bash # 添加主仓库到 remote git remote add upstream https://github.com/plus-pro-components/plus-pro-components.git # 拉取主仓库最新代码 git fetch upstream # 切换至 dev 分支 git checkout dev # 合并主仓库代码 git merge upstream/dev ``` --- --- url: /guide/i18n.md --- # 国际化 PlusProComponents 组件的国际化完全兼容 Element Plus 的国际化，和 Element Plus 一样默认使用英语，如果需要配置国际化，只需要在 Element Plus 语言包的基础上合并 PlusProComponents 的语言包即可。 ## 示例 :::demo locale/basic ::: ## 全局配置 在 Element Plus 的配置上合并语言包。 ```typescript import ElementPlus from 'element-plus' import zhCn from 'element-plus/es/locale/lang/zh-cn' // import en from 'element-plus/es/locale/lang/en' import plusZhCn from 'plus-pro-components/es/locale/lang/zh-cn' // import plusEn from 'plus-pro-components/es/locale/lang/en' app.use(ElementPlus, { locale: { ...zhCn, ...plusZhCn } }) ``` ## ConfigProvider 推荐 在 Element Plus 的 ConfigProvider 合并语言包。 ```html ``` ## CDN 用法 ::: tip 提示 PlusProComponents 的所有语言包全局名称都是以`PlusProComponentsLocale` 开头 然后加上语言包文件名称的驼峰命名。 Element Plus 的所有语言包全局名称都是以 `ElementPlusLocale` 开头 然后加上语言包文件名称的驼峰命名。 ::: 在 CDN 上合并语言包 ```html ``` [支持的语言列表](https://github.com/plus-pro-components/plus-pro-components/tree/dev/packages/locale/lang) * 简体中文(zh-cn) * American English (en) * 日语 (ja) v0.1.4 感谢 [@maojunkun](https://github.com/plus-pro-components/plus-pro-components/commit/8888ce5eb411ac47f2de796529181662022566c1) 贡献 * 繁体中文 (zh-tw) v0.1.14 感谢 [@xiaoxian521](https://github.com/plus-pro-components/plus-pro-components/commit/213f67233b8bb51b00e9854f3ea74be95607eee1) 贡献 * 韩语 (ko) v0.1.14 感谢 [@xiaoxian521](https://github.com/plus-pro-components/plus-pro-components/commit/25a0ddd7e2e687583c54ef1798e4156c0670fffa) 贡献 * 繁体中文 (zh-hk) v0.1.31 感谢 [@bryqiu](https://github.com/plus-pro-components/plus-pro-components/commit/5f6f613dbc23cd13b5b710d197cf9717e6be1ad7) 贡献 如果你需要使用其他的语言，欢迎贡献 [PR](https://github.com/plus-pro-components/plus-pro-components/pulls)，只需在[这里](https://github.com/plus-pro-components/plus-pro-components/tree/dev/packages/locale/lang)添加一个语言配置文件即可。 ## 国际化不起效果？ [issues/125](https://github.com/plus-pro-components/plus-pro-components/issues/125) `plus-pro-components` 小于 `0.0.11` 版本，使用 `npm` 安装依赖，导致`element-plus`版本不一致，进而导致国际化失效，解决方案： * 方案一：使用 `npm` 升级`element-plus`到最新版本即可。 * 方案二： 移除`node_modules` 文件夹，移除`package-lock.json`，然后使用`pnpm i ` 重新安装依赖即可。 --- --- url: /components/type.md --- # 基础 Ts 类型 ::: tip 提示 本页面类型会互相引用，请注意上下文! ::: ## ElementRefType ref 绑定的元素类型 ```ts /** * ref 绑定的元素类型 */ export type ElementRefType = HTMLElement | null ``` ## Timeout setTimeout 类型 ```ts /** * setTimeout 类型 */ export type Timeout = ReturnType ``` ## Interval setInterval 类型 ```ts /** * setInterval 类型 */ export type Interval = ReturnType ``` ## RecordType 普通的对象的泛型 ```ts /** * 普通的对象的类型 */ export type RecordType = { [index: string]: any } ``` ## Nullable 允许 null 的泛型 ```ts /** * 允许null的泛型 */ export type Nullable = T | null ``` ## Mutable 去除只读状态 ```ts /** * 去除只读状态 */ export type Mutable> = { -readonly [K in keyof T]: T[K] } ``` ## PageInfo 分页参数 ```ts /** * 分页参数 */ export interface PageInfo { /** * 默认为1 */ page: number /** * 默认为10 */ pageSize: number } ``` ## ActionBarButtonsRow 表格操作栏按钮配置项的值的类型 ```ts import type { ElMessageBoxOptions } from 'element-plus' import type { Component, Ref, ComputedRef, AppContext, DirectiveArguments } from 'vue' import type { RecordType, ButtonsCallBackParams } from 'plus-pro-components' /** * 按钮属性的类型 */ export type ButtonRowProps = Partial< Mutable > /** * 表格操作栏按钮配置项的值的类型 */ export interface ActionBarButtonsRow { /** * 操作文本 * @version v0.0.8 新增函数类型 */ text: | string | Ref | ComputedRef | (( row: any, index: number, button: ActionBarButtonsRow ) => string | Ref | ComputedRef) /** * 操作按钮唯一code，可用来判断按钮类型 */ code?: string | number /** * `@element-plus/icons-vue` 的图标名称，对ElButton,ElLink 和ElIcon 组件同时生效 */ icon?: Component /** * ElButton,ElLink和ElIcon 组件对应的props * @version v0.1.16 新增函数类型和计算属性 */ props?: | ButtonRowProps | ((row: any, index: number, button: ActionBarButtonsRow) => ButtonRowProps) | ComputedRef /** * ElTooltip组件的props， type 为icon 时生效 */ tooltipProps?: Partial /** * 按钮显示的逻辑 默认 true 显示， 不需要显示给 false * * 可以用来控制权限 */ show?: | boolean | Ref | ComputedRef | (( row: any, index: number, button: ActionBarButtonsRow ) => boolean | Ref | ComputedRef) /** * 操作是不是需要二次确认 默认值为 `false` */ confirm?: | boolean | { /** * ElMessageBox.confirm 的title 默认 `提示` */ title?: string | ((data: ButtonsCallBackParams) => string) /** * ElMessageBox.confirm 的message 默认 `确定执行本次操作` * * @version v0.1.17 新增 当ActionBarProps.confirmType为 `popconfirm` 时 ， 版本中 message 会作为 ElPopconfirm 的title */ message?: string | ((data: ButtonsCallBackParams) => string) /** * ElMessageBox.confirm 的options */ options?: ElMessageBoxOptions /** * ElPopconfirm的props * * 当ActionBarProps.confirmType为 `popconfirm` 时生效 * @version v0.1.17 * @see https://element-plus.org/zh-CN/component/popconfirm.html#attributes */ popconfirmProps?: Partial> /** * ElMessageBox.confirm 的appContext */ appContext?: AppContext | null } /** * 指令，可以用来控制权限，数据类型是二维数组 * @version v0.1.7 * @see https://cn.vuejs.org/guide/extras/render-function.html#custom-directives * */ directives?: DirectiveArguments /** * 点击当前按钮时触发，可与PlusTable的事件 `clickAction` 同时触发； * 操作需要二次确认时：PlusTable的事件 `clickAction`会在确认时触发，而当前的onClick是在点击时触发； * @version v0.1.8 * @param params * @returns */ onClick?: (params: ButtonsCallBackParams) => void /** * 操作需要二次确认时，点击确认时触发 * @version v0.1.8 * @param params * @returns */ onConfirm?: (params: ButtonsCallBackParams) => void /** * 操作需要二次确认时，点击取消时触发， 可与PlusTable的事件 `clickActionConfirmCancel` 同时触发 * @version v0.1.8 * @param params * @returns */ onCancel?: (params: ButtonsCallBackParams) => void } ``` ## ActionBarProps 表格操作栏数据类型 ```ts import type { ComputedRef } from 'vue' import type { ActionBarButtonsRow } from 'plus-pro-components' /** * 表格操作栏数据类型 */ export interface ActionBarProps { /** * 操作栏名称 默认值为 `'操作栏'` * * @version v0.1.0 类型新增ComputedRef */ label?: string | ComputedRef /** * 操作栏固定 默认值为 `'right'` */ fixed?: string /** * 显示出来的按钮个数 默认值为 `3` * @version 0.1.23 新增函数类型 * @default 3 */ showNumber?: number | ((row: RecordType, index: number) => number) /** * 更多按钮展示策略 * true时,showNumber限制的包括更多按钮在内,即包括更多按钮在内,总按钮个数为showNumber * false时,showNumber限制的不包括更多按钮在内，即总按钮个数为showNumber+1,+1是因为'更多'按钮不在showNumber的限制内 * @default false * @version v0.1.20 */ showLimitIncludeMore?: boolean /** * 操作按钮的类型 默认值为 `'link'` */ type?: 'icon' | 'button' | 'link' /** * 操作按钮集合 默认值为 `[]` */ buttons?: ActionBarButtonsRow[] /** * 表格操作栏 el-table-column 的其width 默认值为 `200` */ width?: string | number /** * 表格操作栏 el-table-column 的其他props 默认值为 `{}` */ actionBarTableColumnProps?: Partial /** * 表格操作栏 需要二次确认的类型，默认是 messageBox * @version v0.1.17 */ confirmType?: 'messageBox' | 'popconfirm' /** * 更多按钮的显示类型，text 显示文字和图标，icon 只显示图标 * @default 'text' * @version v0.1.28 */ moreType?: 'text' | 'icon' } ``` ## TableFormRefRow 表格可编辑表单的行 form 的参数类型 ```ts import { ElForm, ElFormItem } from 'element-plus' import type { Ref } from 'vue' /** * 表格可编辑表单的行form 的参数类型 */ export interface TableFormRefRow { /** * 单元格的表单实例 */ formInstance: Ref> /** * 表格的行索引 */ index: number /** * 表格的行索引, 同 index * @version 0.1.20 */ rowIndex: number /** * 单元格的列索引 * @version 0.1.20 */ cellIndex: number /** * 表格的列字段 */ prop: string /** * 单元格的表单开启编辑 * @returns */ startCellEdit: () => void /** * 单元格的表单停止编辑 * @returns */ stopCellEdit: () => void /** * 当前单元格是否可编辑 * @version v0.1.8 */ isEdit: Ref } ``` ## TableCellParams 表格单元格回调参数 ```ts import type { RecordType } from 'plus-pro-components' /** * 表格单元格回调参数 */ export type TableCellParams = { /** * 表格行数据 */ row: RecordType /** * 表格行索引 */ index: number /** * 表格列数据 */ column?: RecordType /** * 表格行索引 同 index * @version v0.1.7 */ rowIndex: number /** * 表格列索引 * @version v0.1.7 */ cellIndex: number /** * 表格store * @version v0.1.7 */ store: RecordType /** * 表格 expanded * @version v0.1.7 */ expanded: boolean /** * 表格 _self * @version v0.1.7 */ _self: RecordType } ``` ## ButtonsCallBackParams 表格点击按钮回调的参数的类型 ```ts import type { TableFormRefRow, TableCellParams, ActionBarButtonsRow } from 'plus-pro-components' /** * 点击按钮回调的参数的类型 */ export interface ButtonsCallBackParams extends TableCellParams { /** * 点击按钮数据 */ buttonRow: ActionBarButtonsRow /** * 解析后的按钮数据中的text * @version v0.1.17 */ text: string /** * 按钮点击事件数据 */ e: MouseEvent /** * 可编辑表单的行form */ formRefs?: TableFormRefRow[] } ``` ## FormChangeCallBackParams 表格表单回调参数 ```ts import type { FieldValueType, TableCellParams } from 'plus-pro-components' /** * formChange回调的参数的类型 */ export interface FormChangeCallBackParams extends TableCellParams { /** * 表单的值 */ value: FieldValueType /** * 当前单元格的prop */ prop: string } ``` ## TableValueType 所有表格列显示的类型 默认是 `undefined` ```ts /** * 所有表格列显示的类型 默认是 `undefined` */ export type TableValueType = | 'img' | 'link' | 'money' | 'tag' | 'progress' | 'copy' | 'code' // v0.1.0 新增 | 'divider' // v0.1.0 新增 | 'avatar' | '' ``` ## FormItemValueType 所有表单的类型 默认是 `input` (`undefined`) ```ts /** * 所有表单的类型 默认是 `input` (`undefined`) */ export type FormItemValueType = | 'autocomplete' | 'cascader' | 'checkbox' | 'color-picker' | 'date-picker' | 'input-number' | 'radio' | 'rate' | 'select' | 'slider' | 'switch' | 'time-picker' | 'time-select' | 'textarea' | 'input' | 'text' | 'plus-radio' | 'plus-date-picker' | 'plus-input-tag' /** * @version 0.1.1 新增 */ | 'transfer' /** * @version 0.1.1 新增 */ | 'tree-select' /** * @version 0.1.21 新增 */ | 'select-v2' | undefined ``` ## FieldValueType 单个表单值的类型 ```ts import type { RecordType } from 'plus-pro-components' /** * 单个表单值的类型 */ export type FieldValueType = | string | number | boolean | null | undefined | Date | string[] | number[] | boolean[] | Date[] | [Date, Date] | [number, number] | [string, string] // v0.1.7 新增 | RecordType ``` ## FieldValues 整体表单值的类型 ```ts import type { FieldValueType } from 'plus-pro-components' /** * 整体表单值的类型 */ export type FieldValues = Record ``` ## PropsItemType 自定义 props 类型 ```ts import type { ComputedRef } from 'vue' import type { FieldValueType } from 'plus-pro-components' /** * 自定义props类型 值支持对象 object，computed，函数和 Promise。 */ export type PropsItemType = any> = | Partial | ComputedRef> | (( value: FieldValueType, data: { row: Record index: number } ) => Partial | Promise>) | Promise> ``` ## OptionsRow 选择框类型 ```ts import type { PropsItemType, RecordType } from 'plus-pro-components' import type { ButtonType } from 'element-plus' import type { VNode } from 'vue' /** * 选择框类型 */ export interface OptionsRow { /** * @version v0.1.15 新增索引类型，用来支持optionsMap @see /components/config.html */ [index: keyof any]: any /** * @version v0.1.15 变更为可选，用来支持optionsMap @see /components/config.html */ label?: number | string /** * @version v0.1.7 新增 RecordType 类型 * @version v0.1.15 变更为可选，用来支持optionsMap @see /components/config.html */ value?: Exclude /** * 小圆点背景色，仅在表格和描述列表中生效 * color 优先级 高于 type */ color?: string /** * 小圆点颜色类型，仅在表格和描述列表中生效 * type 优先级 低于 color， * 只支持 'success' | 'warning' | 'info' | 'primary' | 'danger' */ type?: Exclude /** * 表单子项的props 如 el-checkbox-group下的el-checkbox的props * @version v0.1.25 新增函数类型支持 ((item: OptionsRow) => RecordType) */ fieldItemProps?: RecordType | ((item: OptionsRow) => RecordType) /** * el-checkbox-group下的，每一项el-checkbox的各自插槽(即el-checkbox的default插槽)。 * el-radio-group下的，每一项el-checkbox的内容各自插槽(即el-radio的default插槽)。 * el-select下的，每一项el-option的内容整体插槽(即el-option的default插槽)。 * * @see https://element-plus.org/zh-CN/component/checkbox.html#checkbox-slots * @see https://element-plus.org/zh-CN/component/radio.html#radio-slots */ fieldSlot?: (option?: OptionsRow) => RenderTypes /** * 子选项，仅valueType 为 `cascader` 时生效 */ children?: OptionsRow[] /** * @version 0.1.28 当 valueType 为 select 时，将选项进行分组显示 */ options?: OptionsRow[] } ``` ## OptionsType 选择类型 ```ts import type { OptionsRow } from 'plus-pro-components' /** * 选择类型 支持数组，computed，函数和Promise */ */ export type OptionsType = | OptionsRow[] | ComputedRef | ((props?: PlusColumn) => OptionsRow[] | Promise) | Promise ``` ## PlusFormGroupRow 分步表单配置项 ```ts import type { Component, ComputedRef } from 'vue' import type { PlusColumn, Mutable } from 'plus-pro-components' import type { CardProps } from from 'element-plus' /** * 分组表单配置项 */ export interface PlusFormGroupRow { /** * @version v0.1.17 新增 ComputedRef 类型 */ title: string | ComputedRef /** * @version v0.1.25 新增，用于自动生成分步内容插槽 */ name?: string icon?: Component /** * @desc 分组表单el-card的props，优先级高于整体的cardProps * @version v0.1.1 */ cardProps?: Partial> hideInGroup?: boolean | ComputedRef /** * @version v0.1.25 调整为可选 */ columns?: PlusColumn[] } ``` ## PlusStepFromRow v0.1.8 分步表单配置项 ```ts import type { Component } from 'vue' import type { PlusFormProps } from 'plus-pro-components' /** * 分步表单配置项 */ export interface PlusStepFromRow { title: string /** * @version 0.1.22 变更为可选 */ form: PlusFormProps description?: string icon?: string | Component status?: '' | 'wait' | 'process' | 'finish' | 'error' | 'success' } ``` ## TitleBar 表格标题栏 ```ts import type { Options as SortableOptions } from 'sortablejs' import type { LinkProps } from 'element-plus' import type { Mutable } from 'element-plus/es/utils' export type ColumnSetting = { dragSort?: boolean | Partial /** * 列设置是否需要重置按钮，当值为对象时是el-link按钮的props * @version v0.1.20 * @default true */ reset?: boolean | Partial> /** * 列设置popover的宽度 * @version v0.1.23 * @default 100 */ popoverWidth?: number | string /** * 列设置 checkbox label 隐藏的长度 * @version v0.1.23 * @default 6 */ overflowLabelLength?: number } /** * 标题栏 */ export type TitleBar = { /** * 标题 使用title插槽则此配置不生效 */ title?: string /** * 是否需要刷新 默认false */ refresh?: boolean /** * 是否需要密度控制 默认true */ density?: boolean /** * 是否需要列设置 默认true */ columnSetting?: boolean | ColumnSetting /** * 工具栏 icon 的大小和颜色配置 */ icon?: { /** * icon 的大小 默认 18 */ size?: string /** * icon 的颜色 默认 #606266 */ color?: string } } ``` ## PlusRouteRecordRaw 扩展的路由类型 ```ts import type { RouteRecordRaw } from 'vue-router' import type { VNode, Component } from 'vue' /** * 路由配置类型 * * @description 继承自 vue-router 的 RouteRecordRaw，无侵入，仅仅只扩展 meta，meta除了扩展的属性外，同时支持添加任意自定义属性， * 外链的话 path给 '/'+链接 例： `/https://element-plus.org` * */ export type PlusRouteRecordRaw = Partial> & { /** * meta除了扩展的属性外，同时支持添加任意自定义属性 * */ meta?: { /** * 页面标题 标题存在面包屑和菜单名称显示标题 不存在显示路由的 name name不存在显示路由的 path */ title?: string /** * 图标 */ icon?: Component | VNode | ((route: PlusRouteRecordRaw) => VNode) /** * 排序，默认为0 只对第一级有效 */ sort?: number /** * 在侧边栏菜单中隐藏，默认false 不隐藏 */ hideInMenu?: boolean /** * 隐藏面包屑，默认false 不隐藏 */ hideInBreadcrumb?: boolean /** * 菜单是否禁用 * @see https://element-plus.org/zh-CN/component/menu.html#menu-item-attributes */ disabled?: boolean } children?: PlusRouteRecordRaw[] } ``` --- --- url: /guide.md --- # 简介 **PlusProComponents 灵感来自于[AntDesign ProComponents](https://procomponents.ant.design/)。PlusProComponents 是基于 element-plus 而开发的模板组件，它提供了更高级别的抽象支持，开箱即用。可以显著的提升制作 CRUD 页面的效率，更加专注于页面。** ## 组件列表 * [PlusLayout](/components/layout.html) 页面布局组件，解决布局的问题，提供开箱即用的菜单和面包屑功能。 * [PlusPage](/components/page.html) 页面模板组件，抽象网络请求和表格格式化。 * [PlusTable](/components/table.html) 表格模板组件。 * [PlusSearch](/components/search.html) 搜索模板组件。 * [PlusForm](/components/form.html) 表单模板组件，预设常见布局和行为。 * [PlusDialogForm ](/components/dialog-form.html) 弹窗表单模板组件，预设常见布局和行为。 * [PlusDrawerForm ](/components/drawer-form.html) 抽屉表单模板组件，预设常见布局和行为。 * [PlusDescriptions](/components/descriptions.html) 定义列表模板组件。 ## 组件特性 * 🔥 功能强大：`PlusProComponents` 的组件不仅提供了基本的 UI 展示功能，还具备了复杂的数据操作和业务逻辑处理能力，能够快速构建出功能强大的企业应用。 * 💡 易于使用：`PlusProComponents` 提供了简单易用的 API 和完善的文档，使得开发者能够快速上手并使用其中的组件。 * 📦 高度可定制：`PlusProComponents` 的组件支持多种配置和样式自定义，能够满足不同项目的需求。 * ✅ 兼容 element-plus：`PlusProComponents` 100%兼容和 element-plus 同名的组件，包括属性，事件，方法，插槽等。 * 🛠️ 丰富的组件库：`PlusProComponents` 基于 element-plus 提供了大量的 UI 组件，包括表格、表单、布局等，能够满足大多数企业应用的需求。 * ➕ 使用 TypeScript：`PlusProComponents` 全量使用 TypeScript 编写，和你的 TypeScript 项目无缝衔接。 * 🌐 国际化：`PlusProComponents`提供完备的国际化，与 element-plus 体系打通，无需多余配置。 * 🐋 预设： PlusProComponents 预设基本的样式，与 element-plus 样式一脉相承。 PlusProComponents 预设基本的行为，更少的代码具备更多的功能。 * 🎄 可摇树：开箱即用的 Tree Shaking，只对引入的代码进行打包。 * 🍭 代码零侵入：保持 element-plus 组件兼容的同时，提供更灵活的配置和更强大的功能。 * ✅ 测试：单元测试覆盖率超过 90%，提供稳定性保障。 ## 组件缺点 `PlusProComponents` 是一个基于` Vue` 和 `element-plus` 的组件库，它提供了很多常用的 UI 组件和业务组件，可以方便地帮助开发者快速搭建前端页面。虽然 `PlusProComponents` 具有很多优点，但是也有以下一些缺点： * 学习成本较高：`PlusProComponents` 的组件库比较复杂，学习所有组件可能需要花费较长时间。因此，对于新手开发者来说，学习成本可能会比较高。 * 高度可定制有限：`PlusProComponents` 的组件支持高度可定制，但是仍然不可能保证组件 100%完全自定义，定制需求非常高的项目谨慎使用。 --- --- url: /guide/quickstart.md --- # 快速开始 本节将介绍如何在项目中使用 `PlusProComponents`。 ::: warning 注意 以下使用步骤完成后，请配置[国际化](/guide/i18n.html)，否则可能导致文本显示异常。 ::: ## 使用之前 在开始使用` PlusProComponents` 之前，有必要先了解以下基础知识，我们假设您已经写过 `Vue 3`，并掌握了下面的内容。 * [ES6+](https://es6.ruanyifeng.com/) * [Vue 组件](https://cn.vuejs.org/guide/essentials/component-basics.html) * [单文件组件](https://cn.vuejs.org/guide/scaling-up/sfc.html) * [渲染函数](https://cn.vuejs.org/guide/extras/render-function.html) * [透传 Attributes](https://cn.vuejs.org/guide/components/attrs.html) * [TypeScript](https://www.typescriptlang.org/) (非必须，但是有 TypeScript 基础，使用起来会更加方便。) # 用法 **`plus-pro-components` 和`element-plus` 导入方式需要保持一致。** ## 完整引入 如果你对打包后的文件大小不是很在乎，那么使用完整导入会更方便。 > main.ts ```typescript{8,9,16} import { createApp } from 'vue' // 导入element-plus 及其样式 import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' // 导入plus-pro-components 及其样式 import PlusProComponents from 'plus-pro-components' import 'plus-pro-components/index.css' import App from './App.vue' const app = createApp(App) app.use(ElementPlus) // 使用 app.use(PlusProComponents) app.mount('#app') ``` ### Vue - Official （Volar）支持 如果您使用 Vue - Official （Volar），请在 tsconfig.json 中通过 compilerOptions.type 指定全局组件类型。 ```json // tsconfig.json { "compilerOptions": { // ... "types": ["plus-pro-components/global"] } } ``` ## 自动按需导入 推荐 `PlusProComponents` 提供了基于`ES Module` 的开箱即用的 [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) 功能。 * 1. 安装插件 ```sh pnpm install -D unplugin-vue-components unplugin-auto-import @plus-pro-components/resolver ``` * 2. 配置 `vite.config.ts` 或者配置 `webpack(vue).config.js` [@plus-pro-components/resolver 文档](/ecosystem/resolver.html) ::: code-group ```ts {6,16} [vite.config.ts] // vite.config.ts import { defineConfig } from 'vite' import AutoImport from 'unplugin-auto-import/vite' import Components from 'unplugin-vue-components/vite' import { ElementPlusResolver } from 'unplugin-vue-components/resolvers' import { PlusProComponentsResolver } from '@plus-pro-components/resolver' export default defineConfig({ // ... plugins: [ // ... AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver(), PlusProComponentsResolver()] }) ] }) ``` ```js {5,15} [webpack.config.js] // webpack.config.js const AutoImport = require('unplugin-auto-import/webpack') const Components = require('unplugin-vue-components/webpack') const { ElementPlusResolver } = require('unplugin-vue-components/resolvers') const { PlusProComponentsResolver } = require('@plus-pro-components/resolver') module.exports = { // ... plugins: [ // ... AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [PlusProComponentsResolver(), ElementPlusResolver()] }) ] } ``` ```js {6,17} [vue.config.js] // vue.config.js const { defineConfig } = require('@vue/cli-service') const AutoImport = require('unplugin-auto-import/webpack') const Components = require('unplugin-vue-components/webpack') const { ElementPlusResolver } = require('unplugin-vue-components/resolvers') const { PlusProComponentsResolver } = require('@plus-pro-components/resolver') module.exports = defineConfig({ // ... configureWebpack: { plugins: [ // ... AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [PlusProComponentsResolver(), ElementPlusResolver()] }) ] } }) ``` ::: * 3. 使用组件 > App.vue ```html{3} ``` ### 自动按需导入示例工程 如果你需要新建一个项目，我们推荐使用 Vite。 以下是 plus-pro-components 官方提供的一些示例项目，你可以克隆该项目，并直接拷贝代码来使用。 * [vite-project](https://github.com/plus-pro-components/plus-pro-components-demos/tree/main/vite-project)：使用 Vue 3、Vite 、element-plus、plus-pro-components 搭建应用。 * [vue-cli-project](https://github.com/plus-pro-components/plus-pro-components-demos/tree/main/vue-cli-project)：使用 Vue 3、vue-cli@5 、element-plus、plus-pro-components 搭建应用。 ## 手动导入 手动导入需要导入组件和其对应的样式文件。如下示例： ```html ``` ## CDN 示例 ::: warning 注意 使用 CDN 时，在 HTML 中所有的组件都是小写中划线隔开的形式，不支持单标签。 例如： ```html ``` 需要写成 ```html ``` ::: --- --- url: /components/attrs.md --- # 事件和样式透传 ## 事件透传 ### 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 ``` [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 ``` > 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' } } } ] ``` ### 其他参考上面示例 --- --- url: /components/config.md --- # 通用配置 ::: tip 提示 文中的一些类型来自 基础 Ts 类型 章节，建议先阅读。 ::: 高级组件中除了布局组件[Layout](/components/layout.html)和多选卡片[CheckCardGroup ](/components/check-card-group.html)之外的组件通用配置。 配置的核心字段是`valueType`，渲染的 key 是`prop`（所以需要保证唯一）。 ## columns 配置 TS 类型 `PlusColumn` | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------- | | `prop` （**不可重复**） | 表格对应列内容的字段名 ；在 form/search 中是 el-input 等所有表单项的双向绑定的值；在 descriptions 是 el-descriptions-item 的值对应的字段； **支持`x.y.z`形式的多（无限）级数据形式**； 表单中v0.1.7版本开始支持多级 | `string` | | 是 | | `label` | 表格表头显示的标题 ；在 form 中是 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 的 label；在 descriptions 是 el-descriptions-item 的 label；v0.1.0 版本开始支持计算属性，可用于实现国际化。 | `string`|`ComputedRef`(v0.1.0新增) | | 否 (小于v0.0.10是必须 ) | | `width` | 表格列宽 | `string`| `number` | | 否 | | `minWidth` | 表格列最小宽 | `string`| `number` | | 否 | | **`valueType`** | 值的类型 | `string`([TableValueType](/components/type.html#tablevaluetype) / [FormItemValueType](/components/type.html#formitemvaluetype) ) | | 否 | | `editable` | 当值为`true`时，表格中整列显示的是`valueType`取值对应的可编辑的表单，`valueType`取值为 [FormItemValueType](/components/type.html#formitemvaluetype) | `boolean` | `false` | 否 | | `headerFilter` deprecated v0.0.3 | 表格列设置中禁止表格当前列的表头过滤，已废弃，请使用`disabledHeaderFilter`代替 | `boolean` | `false` | 否 | | `disabledHeaderFilter` v0.0.3 | 表格列设置中禁止表格当前列的表头过滤 | `boolean` | `false` | 否 | | `headerIsChecked` v0.1.22 | 表格列设置中当前表格项是否勾选，默认勾选 | `boolean` | `true` | 否 | | `tableColumnProps` | 表格 column，支持所有[el-table-column 属性](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) （不包含 `label,prop,width,minWidth，formatter`），[支持事件透传](/components/attrs.html) | `object` [ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) | | 否 | | `preview` | 表格列图片预览，仅当 valueType 等于 img 时生效；[ el-image](https://element-plus.org/zh-CN/component/image.html) 图片预览 默认开启 给 false 关闭 | `boolean` | | 否 | | `linkText` | 表格列 link 文字，valueType 等于 link 时生效；有值时则表格的整列都会显示这个值，默认取得是 prop 对应的表格数据 | `string` | | 否 | | `descriptionsItemProps` | 描述行，[el-descriptions-item](https://element-plus.org/zh-CN/component/descriptions.html#descriptionsitem-attributes) 的 props ，[支持事件透传](/components/attrs.html) | `object` [DescriptionsItemProps](https://element-plus.org/zh-CN/component/descriptions.html#descriptionsitem-attributes) | | 否 | | `renderDescriptionsItem`v0.0.2 | 自定义[PlusDescriptions ](/components/descriptions.html) 单行显示内容，在[PlusDescriptions ](/components/descriptions.html)组件中优先级最高，高于 render,renderHTML | `function` | | 否 | | `renderDescriptionsLabel`v0.0.2 | 自定义[PlusDescriptions ](/components/descriptions.html) 单行 label 显示内容 | `function` | | 否 | | `options` | `valueType` 为 `select`|`radio`|`checkbox`|`plus-radio` 时的选项 ，支持数组，computed，函数，和 Promise | `array`|`function`|`promise`[OptionsType](/components/type.html#optionstype) | | 否 | | `optionsMap`v0.1.15 | 对 options 进行映射，仅对`valueType` 为 `select`|`radio`|`checkbox`|`plus-radio` 时生效 | `object` | `{ label: 'label',value: 'value'}` | 否 | | `customGetStatus` | 自定义 options 的显示逻辑，需要返回一个[OptionsRow](/components/type.html#optionsrow)对象。 | `function` | | 否 | | `tooltip` | 展示一个 icon，hover 时展示一些提示信息，v0.1.15新增了计算属性 ComputedRef 类型 | `string` |`ComputedRef`v0.1.15 | ( `object`|`ComputedRef`v0.1.15 [ElTooltipProps](https://element-plus.org/zh-CN/component/tooltip.html#attributes) ) | | 否 | | `render` | 自定义渲染表格/[PlusDescriptions ](/components/descriptions.html)单行显示内容，`render`的优先级最高，高于`renderHTML` 和 `valueType` | `function` | | 否 | | `renderHTML` | 自定义渲染表格/[PlusDescriptions ](/components/descriptions.html)单行显示内容 需要返回一个 html 字符串，`renderHTML`的优先级低于`render`，高于 `valueType`。**谨慎使用，确保 HTML 字符串可信。** | `function` | | 否 | | `renderHeader` | 自定义渲染表格表头显示内容 | `function` | | 否 | | `formatter`v0.1.13 | 格式化表格/PlusDescriptions 显示内容 | `function` | | 否 | | `formProps` | 表格中传递给 [PlusForm](/components/form.html) 的配置，支持所有 [PlusForm](/components/form.html) 的 props，表格编辑状态有效。[支持事件透传](/components/attrs.html) | `object`[PlusFormProps](/components/form.html#form-attributes) ， v0.1.19 新增 computed，函数支持，不支持 Promise | | 否 | | [`formItemProps` ](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) | 传递给 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 的配置，支持所有 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 的 props。值支持对象 object，computed，函数和 Promise。[支持事件透传](/components/attrs.html) | `object`|`function`|`promise`[PropsItemType](/components/type.html#propsitemtype) | | 否 | | `fieldProps` | 传递给具体表单项和表格显示的配置，如 el-input，el-select，el-tag，el-image 的 props。值支持对象 object，computed，函数和 Promise。[支持事件透传](/components/attrs.html) | `object`|`function`|`promise` [PropsItemType](/components/type.html#propsitemtype) | | 否 | | `fieldSlots` | 表单（表格）单个项目的插槽，支持类似 el-input，el-select， el-image ，el-link 等所有表单（表格）单项的插槽 | `object` | | 否 | | `fieldChildrenSlot`v0.0.7 | 自定义表单每一项子项的插槽，例如自定义 el-checkbox-group 下 el-checkbox 的内容 | `function` | | 否 | | `renderField` | 自定义渲染 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 下的 field-item 组件，自定义渲染表单数据双向绑定的核心方法是调用回调函数 `onChange` 把值传给表单 | `function` | | 否 | | `renderLabel` | 自定义渲染 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 的 label 显示内容 | `function` | | 否 | | `hasLabel` | 表单中单个项目是否需要 label，默认 undefined，优先级高于表单的整体的 hasLabel | `boolean` | `undefined` | 否 | | `renderExtra` | 自定义渲染 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 下一行额外的内容 | `function` | | 否 | | `renderPrevious`v0.1.25 | 自定义渲染 [ el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-attributes) 上一行的内容 | `function` | | 否 | | `renderErrorMessage` v0.1.23 | 自定义渲染 [ el-form-item ](https://element-plus.org/zh-CN/component/form.html#formitem-slots) `error`插槽的内容 | `function` | | 否 | | `colProps` | [ el-col](https://element-plus.org/zh-CN/component/layout.html#col-attributes) 的 props。[支持事件透传](/components/attrs.html) | `object` [ColProps](https://element-plus.org/zh-CN/component/layout.html#col-attributes) | `ComputedRef`( v0.1.30 新增) | | 否 | | `order` v0.1.4 | [PlusSearch](/components/search.html) 查询表单中的权重，权重大排序靠前，在 [PlusPage](/components/page.html) 组件中非常有用 | `number` | `0` | 否 | | `hideInDescriptions` | 在 [PlusDescriptions](/components/descriptions.html) 组件中 隐藏 | `boolean` | `false` | 否 | | `hideInForm` | 在 [PlusForm](/components/form.html) 组件中 隐藏 | `boolean` | `false` | 否 | | `hideInTable` | 在 [PlusPage](/components/page.html) 组件中 隐藏 | `boolean` | `false` | 否 | | `hideInSearch` | 在 [PlusSearch](/components/search.html) 组件中 隐藏 | `boolean` | `false` | 否 | | `emptyValue` v0.1.31 | 获取到的值为空（`null`,`undefined`,`''`）时返回的的默认值，优先级高于表格的 `emptyValue`值，column.formatter存在时不生效。 | `string` | `number` | | 否 | ## valueType 可选的表单值 | valueType 表单值 | 对应 element-plus 的表单组件 | 对应 plus-pro-components 的组件 | 对应的表格显示 | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `autocomplete` | [el-autocomplete](https://element-plus.org/zh-CN/component/autocomplete.html) | | 文本显示 | | `cascader` | [el-cascader](https://element-plus.org/zh-CN/component/cascader.html) | | 文本显示 | | `checkbox` | [el-checkbox-group,el-checkbox ](https://element-plus.org/zh-CN/component/checkbox.html) | | 显示值对应`options`的 `label` | | `color-picker` | [el-color-picker](https://element-plus.org/zh-CN/component/color-picker.html) | | 文本显示 | | `date-picker` | [el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) | | 文本显示 默认格式化成` YYYY-MM-DD HH:mm:ss`； v0.1.6 新增 如果 fieldProps 中有`format`(优先)或`valueFormat`，则以`format`或`valueFormat`的格式显示时间 | | `input-number` | [el-input-number](https://element-plus.org/zh-CN/component/input-number.html) | | 文本显示 | | `radio` | [el-radio-group,el-radio](https://element-plus.org/zh-CN/component/radio.html) | | 显示值对应`options`的 `label` | | `radio-button` v0.1.31 | [el-radio-group,el-radio-button](https://element-plus.org/zh-CN/component/radio.html) | | 显示值对应`options`的 `label` | | `rate` | [el-rate](https://element-plus.org/zh-CN/component/rate.html) | | 文本显示 | | `select` | [el-select](https://element-plus.org/zh-CN/component/select.html) | | 显示值对应`options`的 `label` | | `slider` | [el-slider](https://element-plus.org/zh-CN/component/slider.html) | | 文本显示 | | `switch` | [el-switch](https://element-plus.org/zh-CN/component/switch.html) | | 文本显示 | | `time-picker` | [el-time-picker](https://element-plus.org/zh-CN/component/time-picker.html) | | 文本显示 | | `time-select` | [el-time-select](https://element-plus.org/zh-CN/component/time-select.html) | | 文本显示 | | `textarea` | [el-input ](https://element-plus.org/zh-CN/component/input.html#文本域) (type=textarea) | | 文本显示 | | `input`（默认值） | [el-input](https://element-plus.org/zh-CN/component/input.html) 表单默认值 | | 文本显示 | | `text` | [el-text ](https://element-plus.org/zh-CN/component/text.html) | | 文本显示 | | `transfer` v0.1.0 | [el-transfer](https://element-plus.org/zh-CN/component/transfer.html) 穿梭框 | | 文本显示 | | `tree-select` v0.1.1 | [el-tree-select](https://element-plus.org/zh-CN/component/tree-select.html) 树形选择 | | 文本显示 | | `select-v2` v0.1.21 | [el-select-v2](https://element-plus.org/zh-CN/component/select-v2.html) 虚拟化选择器 | | 文本显示 | | `plus-radio` | | [ plus-radio](/components/radio.html) | 显示值对应`options`的 `label` | | `plus-date-picker` | | [plus-date-picker](/components/date-picker.html) | 文本显示 | | `plus-input-tag` | | [plus-input-tag](/components/input-tag.html) | 文本显示 | ## valueType 可选的显示值 | valueType 表格值 | 对应 element-plus/原生的显示组件 | 说明 | 对应的编辑状态组件 | | -------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | `undefined` （默认值） | `span` | 显示默认值，显示文本 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `img` | [el-image](https://element-plus.org/zh-CN/component/image.html) | 显示图片，自带预览，可使用配置项`preview`禁止 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `link` | [el-link](https://element-plus.org/zh-CN/component/link.html) | 显示 [el-link](https://element-plus.org/zh-CN/component/link.html) ，配合配置项`fieldProps`和`linkText` 使用 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `money` | `span` | 显示金钱 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `tag` | [el-tag](https://element-plus.org/zh-CN/component/tag.html) | 显示 [el-tag](https://element-plus.org/zh-CN/component/tag.html) ，配合配置项`fieldProps` 使用 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `progress` | [el-progress](https://element-plus.org/zh-CN/component/progress.html) | 显示 [el-progress](https://element-plus.org/zh-CN/component/progress.html) ，配合配置项`fieldProps` 使用 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `copy` | `span` | 文本后面有可以复制按钮 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `code` | `span` | 显示代码 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `text` | `span` | 显示文本 | [el-text ](https://element-plus.org/zh-CN/component/text.html) | | `avatar`v0.1.0 | [el-avatar](https://element-plus.org/zh-CN/component/avatar.html) | 显示 头像 | [el-input ](https://element-plus.org/zh-CN/component/input.html) | | `divider`v0.1.0 | [el-divider](https://element-plus.org/zh-CN/component/divider.html) | 显示 divider | [el-divider](https://element-plus.org/zh-CN/component/divider.html) | --- --- url: /guide/namespace.md --- # 自定义命名空间 支持 element-plus 的命名空间 Element Plus 提供的默认命名空间为 el。 在特殊情况下，我们需要自定义命名空间。 由于我们使用 sass 书写样式，如果您需要自定义所有命名空间， 我们假定用户使用了 sass 书写样式。 您必须同时设置 `ElConfigProvider` 和 `scss` `$namespace` 以及 `plus-pro-components` `scss`的 `$el-namespace` ## 设置 ElConfigProvider 使用 ElConfigProvider 包装您的根组件。 ```html ``` ## 设置 SCSS 和 CSS 变量 创建 `styles/element/index.scss`: ```scss {5,6,7} @forward 'element-plus/theme-chalk/src/mixins/config.scss' with ( $namespace: 'ep' ); @forward 'plus-pro-components/theme-chalk/src/mixins/config.scss' with ( $el-namespace: 'ep' ); ``` 在 `vite.config.ts` 中导入 `styles/element/index.scss`： > Webpack 也是如此，它需要在 preprocessorOptions 中设置 ```ts import { defineConfig } from 'vite' // https://vitejs.dev/config/ export default defineConfig({ // ... css: { preprocessorOptions: { scss: { additionalData: `@use "~/styles/element/index.scss" as *;` } } } // ... }) ``` --- --- url: /guide/design.md --- # 组件设计 --- --- url: /components/rule.md --- # 组件自定义总则 * 组件都可以自定义。 * 组件自定义方式都有三种方式，优先级`render*`最高，插槽次之。 * 渲染函数（`render*` ） * `j(t)sx` * 插槽 * 组件同时包含`整体插槽`和`单项插槽`的，`单项插槽`的优先级更高。 （`单项插槽`也叫`个性化插槽`） * 组件同时包含`整体渲染函数`和`单项渲染函数`的，`单项渲染函数`的优先级更高。 ## 概念详解 `整体插槽/整体渲染函数`和`单项插槽/单项渲染函数`的概念是对于循环产生组件(元素)，需要自定义循环每一项的时候。 | 概念 | 含义 | 优先级(同时存在时) | | ---------------------- | -------------------------------- | ------------------ | | 单项渲染函数 | 循环每一项的渲染函数都可以自定义 | 最高 | | 整体渲染函数 | 循环每一项的渲染函数都相同 | 高 | | 单项插槽（个性化插槽） | 循环每一项的插槽都可以自定义 | 低 | | 整体插槽 | 循环每一项的插槽都相同 | 最低 | 参考以下伪代码示例： > 整体渲染函数 ```html ``` > 单项渲染函数 ```html ``` --- --- url: /components/breadcrumb.md --- # 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` | | 否 | | ... | ... | ... | ... | ... | :::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 函数的优先级高于插槽** ::: --- --- url: /components/check-card.md --- # CheckCard 多选卡片 ## 简介 PlusCheckCard 集合多种相关联说明信息，并且可被选择的卡片。PlusCheckCardGroup 集成 PlusCheckCard 可以实现多选功能。 ## 基础用法 :::demo check-card/basic ::: ## 不同尺寸 配置 size 尺寸大小，当前可选 large，default，small，不同尺寸仅宽度不同。可以根据需要修改样式自定义大小。 :::demo check-card/size ::: ## 禁用 配置 disabled 可实现禁用。 :::demo check-card/disabled ::: ## 操作栏 :::demo check-card/extra ::: ## 自定义 (render) :::warning 注意 **render 函数的优先级高于插槽** ::: `title`，`description` 和`avatar` 属性支持 字符串和渲染函数 和`undefined`，当值是 undefined 时不渲染。 :::demo check-card/custom ::: ## 自定义 (jsx/tsx) :::demo check-card/tsx ::: ## 自定义 (插槽) :::warning 注意 **插槽优先级低于 render** ::: `title`，`description` 和`avatar` 支持 同名插槽。 :::demo check-card/slot ::: ## CheckCard API ## CheckCard Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------ | -------- | | `model-value / v-model` | 绑定值 | `boolean` | | 否 | | `avatar` | 头像 | `string`/ `function` | | 否 | | `avatarProps` | [el-avatar](https://element-plus.org/zh-CN/component/avatar.html) 的 props | `object` [ ElAvatarProps](https://element-plus.org/zh-CN/component/avatar.html#attributes) | | 否 | | `title` | 标题 | `string`/ `function` | | 否 | | `description` | 描述 | `string`/ `function` | | 否 | | `extra` | 操作栏 | `function` | | 否 | | `size` | 尺寸 | `string` | | 否 | | `disabled` | 禁用 | `boolean` | | 否 | ## CheckCard Events | 名称 | 说明 | 类型 | | -------- | -------------- | -------------------------------------------------------------------- | | `change` | 点击卡片时触发 | `function` | | `extra` | 点击操作栏触发 | `function` | ## CheckCard Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------- | ------------- | ------------------------------------------------------------------- | | `avatar` | 自定义 头像 | `object` | | `title` | 自定义 标题 | `object` | | `description` | 自定义 描述 | `object` | | `extra` | 自定义 操作栏 | `object` | --- --- url: /components/check-card-group.md --- # 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` ) | | 否 | | `options` | 数据数组，支持 [PlusCheckCard](/components/check-card.html#checkcard-attributes) 的所有 `props` (`modelValue` 除外)，数组中`value` 为必选项 | `array` | | 否 | | `size` | 尺寸 | `string` | | 否 | | `disabled` | 禁用 | `boolean` | `false` | 否 | | `multiple` | 多选，当值为`true` 时 `v-model` 的类型是对应的数组。 | `boolean` | `false` | 否 | ## CheckCardGroup Events | 名称 | 说明 | 类型 | | -------- | -------------- | ------------------------------------------------------------------------------------------------------------ | | `change` | 点击卡片时触发 | `function` | | `extra` | 点击操作栏触发 | `function` | ## CheckCardGroup Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------ | ------------- | ------------------------------------------------------------------- | | `avatar`(-\*) | 自定义 头像 | `object` | | `title`(-\*) | 自定义 标题 | `object` | | `description`(-\*) | 自定义 描述 | `object` | | `extra`(-\*) | 自定义 操作栏 | `object` | :::tip 提示 带 `-*` 表示是单项（个性化）插槽，组件会自动根据配置项的 value 生成对应的插槽 ::: --- --- url: /components/date-picker.md --- # DatePicker ## 简介 PlusDatePicker 是由两个 el-date-picker （属性 type 不包含 range）组件组成，核心功能点是两个选择可以独立开来。 ## 基础用法 :::demo date-picker/basic ::: ## DatePicker API ## DatePicker Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------- | | `model-value / v-model` | 绑定值 | `array` | | 否 | | `type` | [el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) 的类型 | `string` | `datetime` | 否 | | `format` deprecated v0.1.0 | 显示在输入框中的格式,已废弃 | `string` | `YYYY-MM-DD HH:mm:ss` | 否 | | `valueFormat` | 绑定值的格式。 不指定则绑定值为 Date 对象 | `string` | `YYYY-MM-DD HH:mm:ss` | 否 | | `rangeSeparator` | 开始时间和结束时间中间的分隔符 | `string` | `/` | 否 | | `disabled` v0.1.14 | 禁用 | `boolean` | `false` | 否 | | `startProps` | 开始的[el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) 的 props（支持所有） | `object` [ElDatePickerProps](https://element-plus.org/zh-CN/component/date-picker.html#%E5%B1%9E%E6%80%A7) | `{}` | 否 | | `endProps` | 结束的[el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) 的 props （支持所有） | `object`[ElDatePickerProps](https://element-plus.org/zh-CN/component/date-picker.html#%E5%B1%9E%E6%80%A7) | `{}` | 否 | | `startDisabledDate` | 开始的[el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) 的 disabledDate | `function` | [startDisabledDate](/components/date-picker.html#startdisableddate) | 否 | | `endDisabledDate` | 结束的[el-date-picker](https://element-plus.org/zh-CN/component/date-picker.html) 的 disabledDate | `function` | [endDisabledDate](/components/date-picker.html#enddisableddate) | 否 | | ... | ... | ... | ... | ... | :::tip 提示 v0.1.0 **`...`表示同时支持所有 [el-date-picker](https://element-plus.org/en-US/component/date-picker.html#attributes) Attributes**，**startProps 和 endProps 里面配置的属性优先级更高** ::: ### startDisabledDate 默认值 ```js const startDisabledDate = (startTime, endValue) => { if (!endValue) return false return startTime.getTime() > new Date(endValue).getTime() } ``` ### endDisabledDate 默认值 ```js const endDisabledDate = (endTime, startValue) => { if (!startValue) return false return endTime.getTime() < new Date(startValue).getTime() } ``` ## DatePicker Events | 名称 | 说明 | 类型 | | -------- | -------------- | ------------------------------------------------------------------- | | `change` | 用户选值时触发 | `function` | ::: tip 提示 el-date-picker 的其他事件的支持写法 如 `blur`，如下示例 ::: 示例： ```html ``` ## Exposes | 名称 | 说明 | 类型 | | --------------------- | ---------------------- | ------------------------------------------------------------------------- | | `startPickerInstance` | 开始的`el-date-picker` | `object` | | `endPickerInstance` | 结束的`el-date-picker` | `object` | --- --- url: /components/descriptions.md --- # Descriptions 描述列表 [描述列表 ](/components/descriptions.html) 是在 [PlusDisplayItem ](/components/display-item.html) 组件上构建而来， 支持其属性、方法 、定义函数和插槽。 ## 基础用法 :::demo descriptions/basic ::: ## 自定义内容 (插槽) v0.0.2 PlusDescriptions 组件会自动根据配置项的 prop 生成对应的插槽， 插槽的生成规则就是 固定 key 值 **\[ plus-desc- ]** 然后加上 配置项的 prop。 :::warning 注意 **插槽 的优先级低于 `renderDescriptionsItem`，高于`render`和`renderHTML`**。 ::: :::demo descriptions/slot ::: ## 自定义内容 (renderDescriptionsItem/jsx) v0.0.2 自定义内容支持 `renderDescriptionsItem`，`render`和`renderHTML`，优先级从高到低。 参考配置[columns](/components/config.html) :::demo descriptions/render ::: ## 自定义 label (插槽) v0.0.2 PlusDescriptions 组件会自动根据配置项的 prop 生成对应的插槽， 插槽的生成规则就是 固定 key 值 **\[ plus-desc-label- ]** 然后加上 配置项的 prop。 :::warning 注意 **插槽 的优先级低于 renderDescriptionsLabel**。 ::: :::demo descriptions/slot-label ::: ## 自定义 label (renderDescriptionsLabel/jsx) v0.0.2 :::warning 注意 **renderDescriptionsLabel 的优先级高于插槽**。 ::: :::demo descriptions/render-label ::: ## 可编辑描述列表 v0.1.17 ::: warning 注意 描述列表中表单数据不会主动和描述列表数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: :::demo descriptions/form ::: ## Descriptions API ## Descriptions Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------- | -------- | | `columns` | 描述列表配置信息 | `array`[PlusColumn\[\]](/components/config.html) | `[]` | 是 | | `data` | 描述列表数据 | `object` | `{}` | 是 | | `border`v0.1.17 | 是否带有边框 ，不会作用于 el-descriptions 本身的 border 属性 。 v0.1.18支持作用于 el-descriptions，仅在不可编辑时（`editable` 为 `false`）生效。 | `boolean` | `true` | 否 | | `editable`v0.1.17 | 描述列表整体可编辑 ，优先级低于单个 [PlusColumn\[editable\]](/components/config.html) 的配置项 | `boolean` | `false` | 否 | | `formProps`v0.1.17 | 描述列表表单的 props，优先级低于单个 [PlusColumn\[formProps\]](/components/config.html) 的配置项 | `object`[PlusFormProps](/components/form.html#form-attributes) | | 否 | | `descriptionsItemProps`v0.1.17 | el-descriptions-item 整体的 props ，优先级低于单个 [PlusColumn\[descriptionsItemProps\] ](/components/config.html)的配置项 | `object`[DescriptionsItemProps](https://element-plus.org/zh-CN/component/descriptions.html#descriptionsitem-attributes) | | 否 | | ... | ... | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-descriptions](https://element-plus.org/zh-CN/component/descriptions.html#descriptions-attributes) Attributes ， border 属性除外。v0.1.18 border 属性支持作用于 el-descriptions，仅在不可编辑时生效。** ::: ## Descriptions Events | 名称 | 说明 | 类型 | | ------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `formChange`v0.1.17 | 描述列表中有可以编辑的表单项目改变时触发 | `function` [FormChangeCallBackParams](/components/type.html#formchangecallbackparams) | ## Descriptions Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------------------------------- | ------------------------------------------------------------ | ---------------------- | | `plus-desc-*` v0.0.2 | 自定义描述，组件会自动根据配置项的 prop 生成对应的插槽 | `{value,data,column}` | | `plus-desc-label-*` v0.0.2 | 自定义描述 label，组件会自动根据配置项的 prop 生成对应的插槽 | `{label,data, column}` | | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-descriptions](https://element-plus.org/zh-CN/component/descriptions.html#descriptions-slots) Slots** ::: ## Exposes | 名称 | 说明 | 类型 | | --------------------------------------- | ---------------------------- | -------------------------------------------------------------- | | `validate`v0.1.17 | 表单校验 | `function` | | `clearValidate`v0.1.17 | 清除所有表单校验 | `function` | | `formRefs`v0.1.17 | 描述列表中所有 form 的实例。 | `array` | --- --- url: /components/dialog.md --- # Dialog 弹窗 ## 基础用法 :::demo dialog/basic ::: ## 自定义 :::demo dialog/slot ::: ## Dialog API ## Dialog Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | -------- | | `model-value / v-model` | 弹窗是否显示绑定值 | `boolean` | `false` | 否 | | `confirmText` | 确认按钮文字 | `string` | `确认` | 否 | | `cancelText` | 取消按钮文字 | `string` | `取消` | 否 | | `confirmLoading` | 确认按钮 loading | `boolean` | `false` | 否 | | `hasFooter` | 是否需要底部按钮 | `boolean` | `true` | 否 | | `top` | 弹窗距离顶部的距离 | `string` | `15vh` | 否 | | `width` | 弹窗宽 | `string` | `460px` | 否 | | `title` | 弹窗标题 | `string` | `弹窗` | 否 | | `footerAlign` | 弹窗底部对齐方式 | `string` | `right` | 否 | | `closeOnClickModal` | [el-dialog](https://element-plus.org/zh-CN/component/dialog.html#attributes) 的 `closeOnClickModal` | `boolean` | `false` | 否 | | `closeOnPressEscape` | [el-dialog](https://element-plus.org/zh-CN/component/dialog.html#attributes) 的 `closeOnPressEscape` | `boolean` | `false` | 否 | | ... | ... | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-dialog](https://element-plus.org/zh-CN/component/dialog.html#attributes) Attributes** ::: ## Dialog Events | 名称 | 说明 | 类型 | | --------- | ---------------- | ----------------------------------------------------- | | `confirm` | 点击确认按钮触发 | `function` | | `cancel` | 点击取消按钮触发 | `function` | | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-dialog](https://element-plus.org/zh-CN/component/dialog.html#%E4%BA%8B%E4%BB%B6) Events** ::: ## Dialog Slots | 插槽名 | 说明 | | --------- | -------- | | `default` | 弹窗内容 | | `header` | 弹窗头部 | | `footer` | 弹窗底部 | --- --- url: /components/dialog-form.md --- # DialogForm 表单 DialogForm 组件是 [PlusDialog](/components/dialog.html)和 [PlusForm](/components/form.html) 组件的组合，是在 [PlusDialog](/components/dialog.html) 组件上自定义 `footer` 的基础上构建而来，除下文提到 [PlusDialogForm](/components/dialog-form.html) 特有的属性和方法外，同时支持 [PlusForm](/components/form.html) 组件的所有自定义函数和插槽。 ::: warning 注意 表单`v-model`绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 [参考 reactive 的局限性](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html#limitations-of-reactive) ::: ## 基础用法 :::demo dialog-form/basic ::: ## 自定义表单项 支持 [PlusForm 自定义表单项](/components/form.html#自定义表单项-renderfield) 自定义表单项 的三种(`renderField`/`slot`/`jsx`)方式。 :::demo dialog-form/slot ::: ## 自定义表单 label 支持 [PlusForm 自定义表单 label](/components/form.html#自定义表单-label-插槽) 自定义表单项 的三种(`renderLabel`/`slot`/`jsx`)方式。 :::demo dialog-form/slot-label ::: ## 自定义底部 `DialogForm` 组件由 [PlusDialog](/components/dialog.html)和 [PlusForm](/components/form.html) 组成，它同时支持两个组件的底部插槽，`DialogForm`默认使用的[PlusDialog](/components/dialog.html)的底部按钮，所以[PlusForm](/components/form.html)组件的 `hasFooter`属性默认给了 `false`。要定义[PlusForm](/components/form.html)组件的底部，需要[PlusDialog](/components/dialog.html)组件的 `hasFooter`属性给 `false`，[PlusForm](/components/form.html)组件的 `hasFooter`属性给`true`。 :::demo dialog-form/custom-footer ::: ## DialogForm API ## DialogForm Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------- | -------- | | `model-value / v-model` | 表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） | `object`[FieldValues](/components/type.html#fieldvalues) | | 否 | | `visible / v-model:visible` | 弹窗显示 | `boolean` | `false` | 否 | | `form` | [PlusForm](/components/form.html) 的 props | `object`[PlusFormProps](/components/form.html#form-attributes) | `{hasFooter:false,footerAlign:'right'}` | 否 | | `dialog` | [PlusDialog](/components/dialog.html) 的 props | `object`[PlusDialogProps](/components/form.html#dialof-attributes) | `{width:"800px",top:"10vh", title:"弹窗表单"}` | 否 | | `hasErrorTip`v0.0.10 | 是否需要校验 message 提示 | `boolean` | `true` | 否 | ## DialogForm Events | 名称 | 说明 | 类型 | | ------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `confirm` | 点击确定按钮触发的事件 | `function` | | `change` | 表单变化触发的事件 | `function` | | `cancel` | 点击取消按钮触发的事件 | `function` | | `close` v0.1.25 | [el-dialog](https://element-plus.org/zh-CN/component/dialog.html#attributes) 的`close`事件 | `function` | | `submitError`v0.0.10 | 点击提交按钮校验不通过触发的事件 | `function` | ## DialogForm Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `dialog-header` | [PlusDialog](/components/dialog.html#dialog-slots) 的 header slot | | | `dialog-footer` | [PlusDialog](/components/dialog.html#dialog-slots) 的 header slot | `{handleConfirm,handleCancel}` 弹窗表单默认的**确定**,**取消**方法 | | `form-footer` | [PlusForm](/components/form.html#form-slots) 的 footer slot， 配置属性 `:form="{hasFooter:true}"` 生效 | `{handleSubmit,handleReset} ` 表单默认的**提交**，**重置**方法 | | `tooltip-icon`v0.0.3 | [PlusForm](/components/form.html#form-slots) 的 tooltip icon | | | `form-group-header` | [PlusForm](/components/form.html#form-slots) 的 group-header slot | `{title,columns,icon}` | | `plus-field-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-label-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项 label，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-extra-*` | [PlusForm](/components/form.html#form-slots)的自定义渲染 el-form-item 下一行额外的内容，组件会自动根据配置项的 prop 生成对应的插槽 | `{column}` | | `plus-previous-*` v0.1.25 | 自定义渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 上一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{column}` | ## Exposes | 名称 | 说明 | 类型 | | -------------- | -------------- | -------------------------------------------------------------------- | | `formInstance` | `el-form` 实例 | `object` | --- --- url: /components/display-item.md --- # DisplayItem 显示单项组件 [PlusTable](/components/table.html) 组件单元格显示的每一项。 ## 基础用法 :::demo display-item/basic ::: ## 单项插槽配置 :::demo display-item/field-slots ::: ## DisplayItem API ## DisplayItem Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------- | -------------- | --------------------------------------------- | ------ | -------- | | `column` | 需要显示的配置 | `object`[PlusColumn](/components/config.html) | | 是 | | `row` | 数据 | `object` | | 是 | | `index` | 索引 | `number` | | ## DisplayItem Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------- | -------------------------------------------------------- | ---------------------------------------------------- | | `plus-cell-*` | 自定义显示项，组件会自动根据配置项的 prop 生成对应的插槽 | `{row,prop,label,fieldProps,value,valueType,column}` | ## Exposes | 名称 | 说明 | 类型 | | --------------- | -------- | ----------------------------------------------------- | | `startCellEdit` | 开起编辑 | `function` | | `stopCellEdit` | 停止编辑 | `function` | --- --- url: /components/drawer-form.md --- # DrawerForm 表单 DrawerForm 组件是 [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html)和 [PlusForm](/components/form.html) 组件的组合，是在 [PlusForm](/components/form.html) 组件上自定义 `footer` 的基础上构建而来，除下文提到 [PlusDrawerForm](/components/drawer-form.html) 特有的属性和方法外，同时支持 [PlusForm](/components/form.html) 组件的所有自定义函数和插槽。 ::: warning 注意 表单`v-model`绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 [参考 reactive 的局限性](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html#limitations-of-reactive) ::: ## 基础用法 :::demo drawer-form/basic ::: ## 自定义表单项 支持 [PlusForm 自定义表单项](/components/form.html#自定义表单项-renderfield) 自定义表单项 的三种(`renderField`/`slot`/`jsx`)方式。 :::demo drawer-form/slot ::: ## 自定义表单 label 支持 [PlusForm 自定义表单 label](/components/form.html#自定义表单-label-插槽) 自定义表单项 的三种(`renderLabel`/`slot`/`jsx`)\`方式。 :::demo drawer-form/slot-label ::: ## DrawerForm API ## DrawerForm Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------- | | `model-value / v-model` | 表单绑定 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） 值 | `object`[FieldValues](/components/type.html#fieldvalues) | | 否 | | `visible / v-model:visible` | 抽屉显示 | `boolean` | `false` | 否 | | `closeOnClickModal` | [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html) 的 `closeOnClickModal` | `boolean` | `false` | 否 | | `closeOnPressEscape` | [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html) 的 `closeOnPressEscape` | `boolean` | `false` | 否 | | `title` | title | `string` | `抽屉表单` | 否 | | `size` | Drawer 窗体的大小, 当使用 number 类型时, 以像素为单位, 当使用 string 类型时, 请传入 'x%', 否则便会以 number 类型解释 | `string`/`number` | `540px` | 否 | | `hasFooter` | 是否需要底部按钮 | `boolean` | `true` | 否 | | `cancelText` | `取消`按钮文本 | `string` | `取消` | 否 | | `confirmText` | `确认`按钮文本 | `string` | `确认` | 否 | | `confirmLoading` | `确认`按钮 loading | `boolean` | `false` | 否 | | `form` | [PlusForm](/components/form.html) 的 props | `object`[PlusFormProps](/components/form.html#form-attributes) | `{hasFooter:false}` | 否 | | `drawer` deprecated v0.1.6 | [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html) 的 props | `object`[ElDrawerProps](https://element-plus.org/zh-CN/component/drawer.html#drawer-attributes) | `{closeOnClickModal:false,closeOnPressEscape:false, title:"抽屉表单"}` | 否 | | `hasErrorTip`v0.0.10 | 是否需要校验 message 提示 | `boolean` | `true` | 否 | | ... v0.1.6 | ... | ... | ... | ... | **`...`表示同时支持所有[ElDrawer Attributes](https://element-plus.org/zh-CN/component/drawer.html#drawer-attributes)** ## DrawerForm Events | 名称 | 说明 | 类型 | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `submit` deprecated v0.0.10 | 点击确定按钮校验通过触发的事件，已废弃，请使用`confirm`代替 | `function` | | `confirm`v0.0.10 | 点击确定按钮校验通过触发的事件 | `function` | | `cancel` | 点击取消按钮触发的事件 | `function` | | `change` | 表单变化触发的事件 | `function` | | `submitError`v0.0.10 | 点击提交按钮校验不通过触发的事件 | `function` | ## DrawerForm Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `drawer-header` | [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html#插槽) 的 header slot | | | `drawer-footer` | [ElDrawer](https://element-plus.org/zh-CN/component/drawer.html#插槽) 的 footer slot | | | `form-footer` | [PlusForm](/components/form.html#form-slots) 的 footer slot | `{handleReset,handleSubmit}` | | `tooltip-icon`v0.0.3 | [PlusForm](/components/form.html#form-slots) 的 tooltip icon | | | `form-group-header` | [PlusForm](/components/form.html#form-slots) 的 group-header slot | `{title,columns,icon}` | | `plus-field-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-label-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项 label，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-extra-*` | [PlusForm](/components/form.html#form-slots)的自定义渲染 el-form-item 下一行额外的内容，组件会自动根据配置项的 prop 生成对应的插槽 | `{column}` | | `plus-previous-*` v0.1.25 | 自定义渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 上一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{column}` | ## Exposes | 名称 | 说明 | 类型 | | ---------------- | ---------------- | ---------------------------------------------------------------------- | | `formInstance` | `el-form` 实例 | `object` | | `drawerInstance` | `el-drawer` 实例 | `object` | --- --- url: /components/form.md --- # Form 表单 ::: warning 注意 表单`v-model`绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 [参考 reactive 的局限性](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html#limitations-of-reactive) ::: ## 基础用法(默认通栏) :::demo form/basic ::: ## 两列 :::demo form/two-columns ::: ## 混合 :::demo form/mixed ::: ## 隐藏 label 表单整体的`hasLabel` 设置为 `false` 时, 隐藏 label。配置[columns](/components/config.html)中的 `hasLabel`可以控制单个表单项的 label 是否显示， 优先级会更高。 :::demo form/has-label ::: ## 异步（动态）数据用法 [PlusColumn](/components/config.html) 配置中的 `options` 支持数组，computed 推荐，函数和 Promise。 [PlusColumn](/components/config.html) 配置中的 `fieldProps`和`formItemProps` 支持对象 object，computed，函数和 Promise。 **常见的使用场景是数据来自后端接口，这里调用后端接口，options 返回 [OptionsRow\[\]](/components/type.html#optionsrow)数组即可。** ::: tip 提示 `options` 建议优先使用 `computed`，可防止用函数在`columns`配置项数据变更后函数重复执行的问题。 使用步骤为： * 1. `columns`配置项外面定义一个 `ref`数组 * 2. 外部异步函数获取到值赋值到 `ref` * 3. `columns`配置项里用 `computed`返回 `ref` 的 `value` 参考下面推荐写法代码示例。 ::: :::demo form/async ::: ## 数据属性联动 [PlusColumn](/components/config.html)的`fieldProps`，`formItemProps`，`options`，`hideInForm`等根据数据变化，动态显示设置。 如下示例，点击状态选择框，当状态为`已解决` 时，`要求1 多选框`会变成 1 个可选， `名称 1，2 输入框`会被禁用，`标签 1 输入框`会被隐藏，`标签 2 输入框`会变成必填。 :::demo form/data-attribute-linkage ::: ## 表单多级数据的双向绑定 v0.1.7 [columns](/components/config.html)中的 `prop`支持 `x.y.z`形式的 多（无限）级数据形式。 :::demo form/multiple-level-form ::: ## 表单配置项 v-model 修饰符的使用 对于输入框想添加`.trim`，`.number` 和 `.lazy` 这些修饰符，可以配置 `columns`中 `fieldProps`的`modelModifiers`属性。 [参考 Vue 官网 v-model 饰符的使用](https://cn.vuejs.org/guide/components/v-model.html#handling-v-model-modifiers) :::demo form/model-modifiers ::: ## 分组表单 配置 `group` 字段，则显示分组。配置 `group` 字段后，`columns` 则不在生效。 `group` 配置参考 [PlusFormGroupRow](/components/type.html#plusformgrouprow) :::demo form/group ::: ## 分组表单动态隐藏 v0.1.4 配置 [PlusFormGroupRow](/components/type.html#plusformgrouprow)\[`hideInGroup`] 字段为`true`，隐藏当前分组，支持计算属性。 :::demo form/group-hide ::: ## 分组表单自定义头部 添加 `group-header` 插槽即可实现。 :::demo form/group-header ::: ## 分组表单自定义每一步内容 v0.1.25 [PlusFormGroupRow](/components/type.html#plusformgrouprow) 新增`value`属性，`PlusForm` 组件会自动根据 `group` 配置项的 `name` 生成对应的插槽，例如下面的配置项，则会自动生成名称叫做 \[ **plus-group-`one`** ]的个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-group-** ] 然后加上`group`配置项的 `name`。 :::demo form/form-group-slot ::: ## 表单单项插槽配置 组件提供 `fieldSlots` 对象可以简易配置表单单项插槽， `fieldSlots` 的插槽配置是根据表单的 [valueType](/components/config.html#valuetype-可选的表单值) 自动进行匹配的， 如： * `valueType` 是 `undefined`(默认值)时，`fieldSlots`的插槽就是给 [ElInput](https://element-plus.org/zh-CN/component/input.html#slots)的。 * `valueType` 是 `autocomplete`时，`fieldSlots`的插槽就是给 [ElAutocomplete](https://element-plus.org/zh-CN/component/autocomplete.html#slots)的。 * 其他以此类推（特殊的除外） **特殊的** * `valueType` 是 `checkbox`时，`fieldSlots`的插槽就是给 [ElCheckboxGroup ](https://element-plus.org/zh-CN/component/checkbox.html#checkboxbutton-api)的。 * `valueType` 是 `radio`时，`fieldSlots`的插槽就是给 [ElRadioGroup ](https://element-plus.org/zh-CN/component/radio.html#radiogroup-slots)的。 要实现更强大的自定义，请使用[自定义表单项](/components/form.html#自定义表单项-插槽)。 ::: warning 注意 valueType 的值对应的组件本身没有插槽时，`fieldSlots`不生效。 ::: :::demo form/field-slots ::: ## 自定义表单底部按钮 组件提供 `footer` 插槽可以自定义表单底部，并提供默认的 **提交**方法、**重置**方法 的作用域插槽参数 `{handleSubmit,handleReset}`。 :::demo form/custom-footer ::: ## 自定义表单项 (插槽) :::warning 注意 **插槽 的优先级低于 renderField，高于 valueType**。 ::: `PlusForm` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-field-`name`** ]和 \[ **plus-field-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-field-** ] 然后加上 配置项的 `prop`。 ```ts import { PlusColumn } from 'plus-pro-components' const tableConfig: PlusColumn[] = [ { label: '名称', // 自动生成对应的插槽 'plus-field-name' prop: 'name' }, { label: '状态', // 自动生成对应的插槽 'plus-field-status' prop: 'status' } ] ``` :::demo form/custom-slot ::: ## 自定义表单项 (renderField) :::warning 注意 **renderField 的优先级高于插槽**。 ::: 自定义表单项的核心方法是定义 `renderField`方法， `renderField` 方法需要返回一个 [VNode](https://cn.vuejs.org/guide/extras/render-function.html) 或 `String` ::: tip 提示 `renderField 返回的值`的`props` 和配置项的`fieldProps`会同时生效，`renderField 返回的值`的`props`优先级高于 `fieldProps`. ::: :::demo form/custom ::: ## 自定义表单项 (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 renderField 函数自定义表单项。 :::demo form/custom-tsx ::: ## 自定义表单 label (插槽) :::warning 注意 **插槽 的优先级低于 renderLabel，高于 label**。 ::: `PlusForm` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-label-`name`** ]和 \[ **plus-label-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-label-** ] 然后加上 配置项的 `prop`。 ```ts import { PlusColumn } from 'plus-pro-components' const tableConfig: PlusColumn[] = [ { label: '名称', // 自动生成对应的插槽 'plus-label-name' prop: 'name' }, { label: '状态', // 自动生成对应的插槽 'plus-label-status' prop: 'status' } ] ``` :::demo form/custom-label-slot ::: ## 自定义表单 label (renderLabel) :::warning 注意 **renderLabel 的优先级高于插槽**。 ::: 自定义表单项的核心方法是定义 `renderLabel`方法， `renderLabel` 方法需要返回一个 [VNode](https://cn.vuejs.org/guide/extras/render-function.html) 或 `String` :::demo form/custom-label ::: ## 自定义表单 label (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 renderField 函数自定义表单项。 :::demo form/custom-label-tsx ::: ## 自定义表单下一行的内容 支持 [renderExtra](/components/config.html) 渲染函数，支持 jsx/tsx，支持插槽，插槽的生成规则就是 固定 key 值 \[ **plus-extra-** ] 然后加上 配置项的 `prop`。 :::demo form/extra ::: ## 自定义表单上一行的内容 v0.1.25 支持 [renderPrevious](/components/config.html) 渲染函数，支持 jsx/tsx，支持插槽，插槽的生成规则就是 固定 key 值 \[ **plus-previous-** ] 然后加上 配置项的 `prop`。 :::demo form/previous ::: ## 自定义表单每一项子项的内容 v0.0.7 ::: warning 注意 * 仅当[PlusColumn](/components/config.html)的`valueType` 为 `checkbox` | `radio` | `select` |`plus-radio`之一时生效。 * 当[PlusColumn](/components/config.html)的`valueType` 为`select`时，不建议定义`label`【无法回显】 * 当 `fieldSlot`函数 和`fieldChildrenSlot`函数同时出现的时候，`fieldSlot`函数的优先级更高。 ::: [PlusColumn](/components/config.html)提供 [fieldChildrenSlot](/components/config.html) 函数可整体自定义表单每一项的子项，[PlusColumn](/components/config.html)的`options`中提供 [fieldSlot](/components/type.html#optionsrow) 函数可单独自定义表单每一项子项的内容。 :::demo form/field-children-slot ::: ## 自定义 tooltip icon v0.0.3 使用`tooltip-icon`插槽 可自定义 tooltip icon。 :::demo form/tooltip-icon-slot ::: ## 所有内置的表单类型 :::demo form/all ::: ## Form API ## Form Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------- | -------- | | `model-value / v-model` | 表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） | `object` [FieldValues](/components/type.html#fieldvalues) | | 否 | | `defaultValues` | 点击重置按钮时 赋值给表单 | `object` [FieldValues](/components/type.html#fieldvalues) | `{}` | 否 | | `columns` | 表单配置信息 | `array`[PlusColumn\[\]](/components/config.html) | `[]` | 否 | | `rowProps` | el-row 的 props | `object`[RowProps](https://element-plus.org/zh-CN/component/layout.html#row-attributes) | | 否 | | `colProps` | el-col 属性 | `object`[ColProps](https://element-plus.org/zh-CN/component/layout.html#col-attributes) | | 否 | | `labelWidth` | el-form 的 labelWidth | `string` | `80px` | 否 | | `labelPosition` | el-form 的 labelPosition | `string` | `left` | 否 | | `labelSuffix` | el-form 的 labelSuffix | `string` | `:` | 否 | | `hasErrorTip` | 是否需要校验 message 提示 | `boolean` | `true` | 否 | | `hasFooter` | 是否需要底部按钮 | `boolean` | `true` | 否 | | `footerAlign` | 底部按钮对齐方式 | `string` | `left` | 否 | | `hasReset` | 是否需要底部按钮 `重置` | `boolean` | `true` | 否 | | `hasLabel` | 是否显示 label，值为`false`时`labelWidth`会被设置为`0`，labelSuffix 会被设置为`''` | `boolean` | `true` | 否 | | `submitLoading` | 确定按钮 loading | `boolean` | `false` | 否 | | `rules` | 表单校验 | `object` [FormRules](https://element-plus.org/zh-CN/component/form.html#form-attributes) | `{}` | 否 | | `group` | 分组表单配置 | `false` / (`array` [PlusFormGroupRow\[\]](/components/type.html#plusformgrouprow) ) | `false` | 否 | | `cardProps`v0.1.1 | 分组表单 [el-card](https://element-plus.org/zh-CN/component/card.html#attributes) 的 props，`group`存在时生效 ，优先级低于`group`配置的每一项的`cardProps` [PlusFormGroupRow](/components/type.html#plusformgrouprow) | `object` [ElCardProps](https://element-plus.org/zh-CN/component/card.html#attributes) | `false` | 否 | | `submitText` | 提交按钮文字 | `string` | `提交` | 否 | | `resetText` | 重置按钮文字 | `string` | `重置` | 否 | | `prevent`v0.1.13 | 阻止 el-form 的默认提交表单行为 | `boolean` | `false` | 否 | | `collapseTransition`v0.1.15 | 是否需要表单变化动画，**在[PlusSearch](/components/search.html#search-attributes)和[PlusStepsForm ](/components/steps-form.html#stepsform-attributes)组件中效果明显** | `boolean` | `true` | 否 | | `collapseDuration`v0.1.15 | 表单变化动画持续时长(单位：ms) | `number` | `300` | 否 | | `clearable`v0.1.18 | 表单内所有表单项的是否可清除，会显示清除图标，优先级低于配置项的 [PlusColumn\[fieldProps\]](/components/config.html)里的`clearable` | `boolean` | `true` | 否 | | ... | ... | ... | ... | ... | **`...`表示同时支持所有[ElForm Attributes](https://element-plus.org/zh-CN/component/form.html#form-attributes)** :::tip 提示 **[ElForm](https://element-plus.org/zh-CN/component/form.html#form-attributes) 的 model 参数已在组件内部处理，一般不需要传**。 ::: ## Form Events | 名称 | 说明 | 类型 | | ------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | | `submit` | 点击提交按钮校验通过触发的事件 | `function` | | `change` | 表单变化触发的事件 | `function` | | `reset` | 点击重置按钮触发的事件 | `function` | | `submitError` | 点击提交按钮校验不通过触发的事件 | `function` | | ... | ... | ... | **`...`表示同时支持所有[ElForm Events](https://element-plus.org/zh-CN/component/form.html#form-%E4%BA%8B%E4%BB%B6)** :::tip 提示 如 el-form 的 validate，如下示例 ::: 示例： > 模板中 ```html ``` > setup 中 ```ts const handleValidate = (prop: FormItemProp, isValid: boolean, message: string) => { console.log(dropdownItem) } ``` ## Form Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `default` | 表单的内容 默认是 `PlusFormItem` 组件 | | | `footer` | 表单底部按钮 | `{handleReset,handleSubmit}` | | `tooltip-icon`v0.0.3 | tooltip icon | | | `group-header` | 分组表单头部，配置 `group` 字段时生效。 | `{title,columns,icon,index}` v0.1.17 新增`index` | | `plus-field-*` | 自定义表单项，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-label-*` | 自定义表单项 `label`，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-extra-*` | 自定义渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 下一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{column}` | | `plus-previous-*` v0.1.25 | 自定义渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 上一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 | `{column}` | | `plus-group-*` v0.1.25 | 分组表单自定义每一步内容，组件会自动根据分组表单`group`配置项的 `name` 生成对应的插槽 | `{title,columns,icon,index,name}` | ## Exposes | 名称 | 说明 | 类型 | | -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------- | | `formInstance` | `el-form` 实例 | `object` | | `handleReset` | 表单默认的重置方法，同时会清空校验 | `function` | | `handleSubmit` | 表单默认的提交方法，有校验的话，校验成功返回`true`，失败返回`false` | `function` | **拿到 formInstance 后支持所有[ElForm 方法](https://element-plus.org/zh-CN/component/form.html#form-exposes)** ::: tip 提示 如 `validate`,`validateField`等 ::: --- --- url: /components/form-item.md --- # FormItem 表单单项组件 [PlusForm](/components/form.html) 组件的每一项。 ::: warning 注意 表单`v-model`绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 [参考 reactive 的局限性](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html#limitations-of-reactive) ::: ## 基础用法 设置 `valueType` 控制表单的类型。 :::demo form-item/basic ::: ## 异步（动态）数据用法 [PlusColumn](/components/config.html) 配置中的 `options` 支持数组， computed，函数和 Promise。 :::demo form-item/async ::: ## 自定义表单项 (插槽) :::warning 注意 **插槽 的优先级低于 renderField，高于 valueType**。 ::: `PlusFormItem` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-field-`name`** ]和 \[ **plus-field-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-field-** ] 然后加上 配置项的 `prop`。 ```html ``` :::demo form-item/custom-slot ::: ## 自定义表单项 (renderField) :::warning 注意 **renderField 的优先级高于插槽**。 ::: 自定义表单项的核心方法是定义 `renderField`方法， `renderField` 方法需要调用 vue 的[渲染函数 h](https://cn.vuejs.org/guide/extras/render-function.html) 返回一个 `VNode` ::: tip 提示 `renderField 返回的值`的`props` 和配置项的`fieldProps`会同时生效，`renderField 返回的值`的`props`优先级高于 `fieldProps`. ::: :::demo form-item/custom ::: ## 自定义表单项 (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 renderField 函数自定义表单项。 :::demo form-item/custom-tsx ::: ## 自定义表单 label (插槽) :::warning 注意 **插槽 的优先级低于 renderLabel，高于 label**。 ::: `PlusFormItem` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-label-`name`** ]和 \[ **plus-label-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-label-** ] 然后加上 配置项的 `prop`。 ```html ``` :::demo form-item/custom-label-slot ::: ## 自定义表单 label (renderLabel) :::warning 注意 **renderLabel 的优先级高于插槽**。 ::: 自定义表单项的核心方法是定义 `renderLabel`方法， `renderLabel` 方法需要调用 vue 的[渲染函数 h](https://cn.vuejs.org/guide/extras/render-function.html) 返回一个 `VNode` :::demo form-item/custom-label ::: ## 自定义表单 label (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 renderField 函数自定义表单项。 :::demo form-item/custom-label-tsx ::: ## 所有支持的类型 :::demo form-item/all ::: ## FormItem API ## FormItem Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | | `model-value / v-model` | 表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） | `object`[FieldValues](/components/type.html#fieldvalues) | | 否 | | `label` | el-form-item 的 label | `string` | | 是 | | `prop` | el-input 等所有表单项的双向绑定的值； | `string` | | 是 | | `valueType` | 值的类型 | `string`[FormItemValueType](/components/type.html#formitemvaluetype) | | 否 | | `options` | el-select，el-radio-group，el-checkbox-group 选项 ，支持数组，函数，和 Promise | `array/function/promise`[OptionsType](/components/type.html#optionstype) | | 否 | | `tooltip` | 展示一个 icon，hover 时展示一些提示信息 | `string` / (`object`[ElTooltipProps](https://element-plus.org/zh-CN/component/tooltip.html#attributes) ) | | 否 | | `renderField` | 自定义渲染 el-form-item 下的 field-item 组件，自定义渲染同步表单的值的核心方法是调用 onChange 回调把值传给表单 | `function` | | 否 | | `formItemProps` | 传递给 el-form-item 的配置，支持所有 el-form-item 的 props。值支持对象 object，computed，函数和 Promise。 | `object/function/promise`[PropsItemType](/components/type.html#propsitemtype) | | 否 | | `fieldProps` | 传递给具体表单项和表格显示的配置，如 el-input，el-select 的 props。 值支持对象 object，computed，函数和 Promise。 | `object/function/promise`[PropsItemType](/components/type.html#propsitemtype) | | 否 | | `renderLabel` | 自定义渲染 el-form-item 下 label 行显示内容 | `function` | | 否 | ## FormItem Slots | 插槽名 | 说明 | 作用域插槽参数 | | -------------- | -------------------------------------------------------------- | ------------------------------------------ | | `plus-field-*` | 自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-label-*` | 自定义表单项 label，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | ## Exposes | 名称 | 说明 | 类型 | | ------------------ | ------------------------------ | ------------------------------------------------------------------------ | | `formItemInstance` | el-form-tem 实例 | `object` | | `fieldInstance` | 具体的表单单项实例 如 el-input | `object` | --- --- url: /components/header.md --- # Header 页头 ## 简介 PlusHeader 页面头部。 ## 基础用法 :::demo header/basic ::: ## 自定义左侧和右侧 (renderHeaderLeft/renderHeaderRight) :::demo header/render ::: ## 自定义左侧和右侧 (插槽) :::demo header/slots ::: ## 用户下拉自定义 :::demo header/dropdown ::: ## Header API ## Header Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------- | | `logo` | logo | `string` | `https://plus-pro-components.com/logo.png` | 否 | | `title` | 标题 | `string` | `PlusProComponents` | 否 | | `trigger` | 名称头像下拉触发方式 | `string` | `click` | 否 | | `hasUserInfo` | 是否需要用户信息 | `boolean` | `true` | 否 | | `userInfo` | 用户信息 | `object` | `{}` | 否 | | `logoutText` | 退出登录文字 | `string` | `退出登录` | 否 | | `dropdownList` | 下拉其他选项 | `array` | `[]` | 否 | | `renderHeaderLeft` | 自定义左侧 | `function` | | 否 | | `renderHeaderRight` | 自定义右侧 | `function` | | 否 | ## Header Events | 名称 | 说明 | 类型 | | ------------------- | ------------------ | --------------------------------------------------------- | | `clickDropdownItem` | 点击下拉单项时触发 | `function` | ## Header Slots | 插槽名 | 说明 | 作用域插槽参数 | | -------------- | -------------- | ------------------ | | `header-left` | 自定义头部左侧 | `{logo,title}` | | `header-right` | 自定义头部右侧 | `{userInfo,title}` | --- --- url: /components/input-tag.md --- # InputTag 输入标签 InputTag 组件由 [ElTag](https://element-plus.org/zh-CN/component/tag.html) 和[ElInput](https://element-plus.org/zh-CN/component/input.html) 组成。 ::: tip 提示 element-plus 官方已经在v2.9.0版本中支持了 [input-tag](https://element-plus.org/zh-CN/component/input-tag.html) 组件。 ::: ## 基础用法 :::demo input-tag/basic ::: ## 数量限制 :::demo input-tag/limit ::: ## 禁用 :::demo input-tag/disabled ::: ## 触发方式 默认 `失去焦点`、`按回车键`、`按空格键`都可以触发，这几种触发方式可以任意组合。 :::demo input-tag/trigger ::: ## InputTag API ## InputTag Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------- | -------- | | `model-value / v-model` | 输入标签组件绑定值 （**不可重复**） | `array` | | 否 | | `trigger` | 触发输入内容变成标签的方式 | `array`/`string` | `['blur', 'enter', 'space']` | 否 | | `limit` | tag 的最大数量 | `number` | | 否 | | `formatTag`v0.0.3 | 格式化标签内容 | `function` | | 否 | | `retainInputValue`v0.0.3 | 是否保留输入框的内容 | `boolean` | `false` | 否 | | `tagProps` | [ElTag](https://element-plus.org/zh-CN/component/tag.html#tag-attributes) 的 props | `object` | | 否 | | `inputProps` | [ElInput](https://element-plus.org/zh-CN/component/input.html) 的 props | `object` | | 否 | | `disabled` v0.1.14 | 禁用 | `boolean` | `false` | 否 | ## InputTag Events | 名称 | 说明 | 类型 | | ------------------------------- | -------------------- | ------------------------------------------------------------------------------------- | | `change` | tag 数据改变时触发 | `function` | | `remove`v0.0.3 | 移除 tag 触发 | `function` | | `blur`v0.0.3 | 输入框失去焦点时触发 | `function` | | `enter`v0.0.3 | 按下回车键触发 | `function` | | `space`v0.0.3 | 按下空格键触发 | `function` | ## Exposes | 名称 | 说明 | 类型 | | --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `inputInstance` | [ElInput](https://element-plus.org/zh-CN/component/input.html) 实例 | `object` | | `tagInstance` | [ElTag](https://element-plus.org/zh-CN/component/tag.html) 实例 | `object` | --- --- url: /components/layout.md --- # Layout ## 简介 PlusLayout 是由 [PlusBreadcrumb ](/components/breadcrumb.html)， [PlusHeader ](/components/header.html)， [PlusSidebar ](/components/sidebar.html)三个组件组合而成，它解决了布局的问题，提供开箱即用的菜单（多级）和面包屑功能。 ## 基础用法 :::demo layout/basic ::: ## Layout API ## Layout Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | --------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------- | -------- | | `breadcrumbProps` | PlusBreadcrumb 的 props | `object` [PlusBreadcrumb ](/components/breadcrumb.html#breadcrumb-attributes) | | 否 | | `headerProps` | PlusHeader 的 props | `object`[PlusHeader ](/components/header.html#header-attributes) | | 否 | | `sidebarProps` | PlusSidebar 的 props | `object`[PlusSidebar ](/components/sidebar.html#sidebar-attributes) | | 否 | | `scrollbarProps` | scrollbar 的 props | `false` / `object`[ScrollbarProps ](https://element-plus.org/zh-CN/component/scrollbar.html#attributes) | `{always:true}` | 否 | | `backtop` | backtop 的 props | `false` / `object`[BacktopProps ](https://element-plus.org/zh-CN/component/backtop.html#attributes) | `true` | 否 | | `hasSidebar`v0.1.15 | 是否需要侧边栏 | `boolean` | `true` | 否 | | `hasHeader`v0.1.15 | 是否需要页头 | `boolean` | `true` | 否 | | `hasBreadcrumb`v0.1.15 | 是否需要面包屑 | `boolean` | `true` | 否 | ::: tip 提示 子组件事件写法示例 如 [PlusSidebar ](/components/sidebar.html) 的事件 `toggleCollapse`和 [PlusHeader ](/components/header.html)的事件`clickDropdownItem`。 参考 vue 官方文档 **[透传 Attributes](https://cn.vuejs.org/guide/components/attrs.html)**，如下示例 ::: 示例： > 模板中 ```html ``` > setup 中 ```ts const handleClickDropdownItem = (dropdownItem: { label: string; value: string }) => { console.log(dropdownItem) } const handleToggleCollapse = (collapse: boolean) => { console.log(collapse) } ``` ## Exposes | 名称 | 说明 | 类型 | | --------------------- | ------------------ | -------- | | `plusSidebarInstance` | PlusSidebar 的实例 | `object` | ## Slots | 插槽名 | 说明 | 作用域插槽参数 | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `default` | 内容，一般需要给 [RouterView](https://router.vuejs.org/zh/guide/#RouterView-%E5%92%8C-RouterLink) 组件，配合路由信息展示页面 | | | `layout-extra` | 定义面包屑上方，header 下方的一块区域 | | | `breadcrumb-item-title` | 自定义[PlusBreadcrumb ](/components/breadcrumb.html)面包屑显示 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `header-left` | 自定义[PlusHeader ](/components/header.html)头部左侧 | `{logo,title}` | | `header-right` | 自定义[PlusHeader ](/components/header.html)头部右侧 | `{userInfo,title}` | | `sidebar-item` | 自定义 [PlusSidebar ](/components/sidebar.html)菜单的 menuItem | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-sub` | 自定义 [PlusSidebar ](/components/sidebar.html)菜单的 subMenu | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-item-title` | 自定义 [PlusSidebar ](/components/sidebar.html)菜单每项标题显示 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-extra` | 自定义 [PlusSidebar ](/components/sidebar.html)在菜单头和菜单之间 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | --- --- url: /components/page.md --- # Page 页面 Page 组件是 [PlusSearch](/components/search.html)和 [PlusTable](/components/table.html) 组件的组合。 ## 基础用法 :::demo page/basic ::: ## 搜索值响应（v-model:search-values） v0.1.31 通过 `v-model:search-values` 绑定搜索表单的值，当搜索表单中任意字段发生变化时，绑定的值会实时更新。同时支持 `searchChange` 事件，可以获取变化的字段信息。 :::demo page/model-value ::: ## 手动控制搜索值 v0.1.17 可使用实例中提供的方法`setSearchFieldsValue` `getSearchFieldsValue` `clearSearchFieldsValue`手动控制搜索值。 :::demo page/setValue ::: ## 搜索参数处理 配置`before-search-submit`方法，可在请求前替换参数名。 :::demo page/replace-search-key ::: ## 默认搜索参数 配置 `search.defaultValues`属性，设置默认搜索参数，当页面**初始化**和**点击搜索重置按钮**时 [PlusSearch](/components/search.html) 组件的`model-value / v-model` 会被设置为 defaultValues。 :::demo page/default-search-values ::: ## 默认分页参数 配置 `defaultPageInfo`属性，可以修改默认的分页参数，`defaultPageInfo`的`TS`类型为[PageInfo](/components/type.html#pageinfo)。配置`defaultPageSizeList`属性可以修改分页列表，其他分页属性配置可以使用`pagination`属性。 :::demo page/default-page ::: ## 自定义搜索按钮 使用`search-footer` 自定义搜索按钮. :::demo page/search-footer ::: ## 自定义搜索表单插槽的使用 v0.1.25 当 [PlusPage](/components/page.html) 组件的`search-slot`属性为`true`时，表单相关的 `plus-field-*`、 `plus-label-*`（只对搜索表单生效）、 `plus-extra-*`、 `plus-previous-*`、 插槽会作用于 到 [PlusSearch](/components/search.html) 组件，默认插槽都是作用于 [PlusTable](/components/table.html) 组件的（表格开启编辑时）。 :::demo page/search-slot ::: ## 搜索和表格展示顺序控制 v0.1.4 默认情况下搜索和表格会按`columns`的顺序展示，搜索可以使用[order](/components/config.html) 参数控制展示顺序(默认值为`0`)，[order](/components/config.html) 越大越靠前。 :::demo page/order ::: ## 增删改查 (CRUD) 典型的增删改查。 :::demo page/crud ::: ## Page API ## Page Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | -------- | | `search-values / v-model:search-values`v0.1.31 | 搜索表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） | `object`[FieldValues](/components/type.html#fieldvalues) | | 否 | | `columns` | 配置信息 | `array`[PlusColumn\[\]](/components/config.html) | `[]` | 是 | | `request` | request 是 Page 最重要的 API，request 会接收一个对象。对象中必须要有 data，如果需要手动分页 total 也是必需的。request 会接管 loading 的设置，同时在查询表单查询和 params 参数发生修改时重新执行。同时 查询表单的值和 params 参数也会带入。 | `function` | | 是 | | `search` | [PlusSearch](/components/search.html) 的 props，不包含`model-value / v-model`，`columns`，`searchLoading`属性。 | `false` / (`object`[PlusSearchProps](/components/search.html#search-attributes) ) | `{}` | 否 | | `table` | [PlusTable](/components/table.html) 的 props，不包含`tableData`,`columns`，`loadingStatus`,`pagination`属性。 | `object`[PlusTableProps](/components/table.html#table-attributes) | `{}` | 否 | | `params` | request 的 params 其他参数，默认会带 pageSize，page 和 [PlusSearch](/components/search.html)组件中的值，它的优先级高于其他配置。 | `object` | `{}` | 否 | | `postData` | 对通过 request 获取的数据进行处理 | `function` | | 否 | | `beforeSearchSubmit` | 搜索之前进行一些修改 | `function` | | 否 | | `defaultPageInfo` | 默认分页参数 | `object` [PageInfo](/components/type.html#pageinfo) | `{page:1, pageSize:10}` | 否 | | `defaultPageSizeList` | 默认分页列表 | `array` | `[10, 20, 30, 40, 50, 100, 200, 300, 400, 500]` | 否 | | `pagination` | 分页组件[PlusPagination](/components/pagination.html) 的 props，不包含`total`，`modelValue`，`pageSizeList`。不需要分页可以给`false`(v0.1.0 新增)。 | `object`[PlusPagination Props](/components/pagination.html#pagination-attributes) | `false`( v0.1.0 新增) | | 否 | | `isCard` | 表格和搜索是否需要 el-card 包裹 | `boolean` | `true` | | `dividerProps`v0.1.0 | [el-divider](https://element-plus.org/zh-CN/component/divider.html#attributes) 的 props | `object`[ElDividerProps](https://element-plus.org/zh-CN/component/divider.html#attributes) | `false` | `false` | 否 | | `searchCardProps` | 搜索外层的 [el-card](https://element-plus.org/zh-CN/component/card.html#attributes) 的 props ，当 isCard 为 true 时生效 | `object`[ElCardProps](https://element-plus.org/zh-CN/component/card.html#attributes) | `{}` | 否 | | `tableCardProps` | 表格外层的 [el-card](https://element-plus.org/zh-CN/component/card.html#attributes) 的 props ，当 isCard 为 true 时生效 | `object`[ElCardProps](https://element-plus.org/zh-CN/component/card.html#attributes) | `{}` | 否 | | `immediate`v0.0.9 | 是否立即执行`request`获取表格数据,如为`false`,组件渲染完成后将不会主动调用`request` | `boolean` | `true` | 否 | | `pageInfoMap`v0.1.0 | request 默认分页参数字段是 `page`, `pageSize`,可以使用此参数自定义分页参数 | `object` | `{page:'page',pageSize:'pageSize'}` | 否 | | `searchSlot`v0.1.25 | 自定义的表单插槽默认作用于 [PlusTable](/components/table.html)， 当`searchSlot`位`true`时， 自定义的表单插槽作用于 [PlusSearch](/components/search.html) 组件 。 | `boolean` | `false` | 否 | | `resetSearch` v0.1.31 | 是否在重置后进行搜索 | `boolean` | `true` | 否 | ## Page Events | 名称 | 说明 | 类型 | | ---------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `requestError` | 数据加载失败时触发 | `function` | | `requestComplete`v0.1.5 | 数据加载完成时触发 | `function` | | `search` | 点击搜索按钮时触发，（并将 page 置为 1 ，然后重新加载v0.1.8 ） | `function` | | `reset` | 点击重置按钮时触发，并将 page 置为 1 ，然后重新加载 | `function` | | `searchChange`v0.1.31 | 搜索表单中任意字段值变化时触发 | `function` | | `paginationChange` | 分页改变时触发 | `function` | ::: tip 提示 支持 [PlusSearch](/components/search.html) 和 [PlusTable](/components/table.html) 的所有事件，如 [PlusSearch](/components/search.html) 的`search`, [PlusTable](/components/table.html) 的`row-click`等，如下示例 ::: 示例： ```html ``` ## Page Slots | 插槽名 | 说明 | 作用域插槽参数 | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `table-title` | [PlusTable](/components/table.html) 表格标题 | | | `table-toolbar` | [PlusTable](/components/table.html) 工具栏左侧 | | | `table-expand` | [PlusTable](/components/table.html) 展开行 | | | `table-append` | [PlusTable](/components/table.html)（el-table） 最后一行 | | | `table-empty` | [PlusTable](/components/table.html) （el-table）空状态 | | | `search-footer` | [PlusSearch](/components/search.html) 的 footer | | | `pagination-left`v0.0.3 | [PlusTable](/components/table.html)分页器左侧内容 （默认生效，`align` 属性默认是 `right`） | | | `pagination-right`v0.0.3 | [PlusTable](/components/table.html) 分页器右侧内容 （`align` 属性是 `left`时生效） | | | `action-bar-more-icon`v0.0.3 | [PlusTable](/components/table.html)操作栏更多旁边的 icon | | | `tooltip-icon`v0.0.3 | [PlusTable](/components/table.html) 表格表头 tooltip icon | | | `drag-sort-icon`v0.0.3 | [PlusTable](/components/table.html)表格拖拽行 和 列设置里拖拽 icon | | | `column-settings-icon`v0.0.3 | [PlusTable](/components/table.html)表格表头 列设置 icon | | | `density-icon`v0.0.3 | [PlusTable](/components/table.html)表格表头 密度 icon | | | `edit-icon`v0.1.4 | [PlusTable](/components/table.html) 表格处于编辑状态时的 icon | | | `extra`v0.1.5 | 表格和搜索中间位置的插槽 | | | `plus-cell-*` | 自定义表格项，组件会自动根据配置项的 prop 生成对应的插槽 | `object` | | `plus-header-*` | 自定义表格项 header，组件会自动根据配置项的 prop 生成对应的插槽 | `object` | | `plus-field-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 ，表格需要开启属性 [PlusColumn\['editable'\]](/components/config.html)，搜索需要开启`searchSlot` | `object` | | | | `plus-label-*` v0.1.25 | 自定义**搜索**表单项 `label`，组件会自动根据配置项的 `prop` 生成对应的插槽 ，**此插槽只对搜索表单生效，搜索需要开启`searchSlot`** | `{prop,label,fieldProps,valueType,column}` | | `plus-extra-*` v0.1.25 | 自定义表单渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 下一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 ，表格需要开启属性 [PlusColumn\['editable'\]](/components/config.html)，搜索需要开启`searchSlot` | `{column}` | | `plus-previous-*` v0.1.25 | 自定义表单渲染[el-form-item](https://element-plus.org/zh-CN/component/form.html#formitem-api) 上一行额外的内容，组件会自动根据配置项的 `prop` 生成对应的插槽 ，表格需要开启属性 [PlusColumn\['editable'\]](/components/config.html)，搜索需要开启`searchSlot` | `{column}` | ## Page Exposes | 名称 | 说明 | 类型 | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `plusSearchInstance` | [PlusSearch](/components/table.html)的实例 | `object` | | `plusTableInstance` | [PlusTable](/components/table.html)的实例 | `object` | | `getList` | 获取数据方法，可以用来重新加载数据 | `function` | | `handleRest` deprecated v0.1.14 | 重置搜索数据，并将 page 置为 1 ，然后重新加载 getList | `function` | | `handleReset`v0.1.14 | 重置搜索数据，并将 page 置为 1 ，然后重新加载 getList | `function` | | `setSearchFieldsValue`v0.1.17 | 手动设置搜索值 ，传入一个对象参数，只会修改对象参数中对应值。 | `function` | | `getSearchFieldsValue`v0.1.17 | 手动获取搜索值 ，传入一个字段`key`则获取的是字段`key`对应的值，默认返回所有值。 | `function` | | `clearSearchFieldsValue`v0.1.17 | 手动清空搜索值 | `function` | | `setTableData`v0.1.23 | 手动设置表格数据和分页总数。不给参数会清空表格数据。 | `function` | --- --- url: /components/pagination.md --- # Pagination 分页 ## 基础用法 :::demo pagination/basic ::: ## 对齐方式 支持 `left`、`right`、`center`(v0.1.28新增) 三种对齐方式。 :::demo pagination/align ::: ## 左右侧内容 自定义 v0.0.2 `align` 属性默认是 `right`，插槽 `pagination-left` 默认生效。要使用`pagination-right` 插槽，需要设置`align` 属性为 `left`。 v0.1.28 设置 `align` 为 `center` 时分页器将居中显示，且左右两个插槽都可使用。 :::demo pagination/slot ::: ## Pagination API ## Pagination Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -------- | | `align` | 对齐方式 | `string` （`center`v0.1.28 新增） | `right` | 否 | | `model-value / v-model` | 分页值 | `object` [PageInfo](/components/type.html#pageinfo) | `{ page: 1,pageSize: 10}` | 否 | | `total` | 总数 | `number` | `0` | 否 | | `pageSizeList` | 分页列表 | `array` | `[10, 20, 30, 40, 50, 100, 200, 300, 400, 500]` | 否 | | ... | ... | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-pagination](https://element-plus.org/zh-CN/component/pagination.html#%E5%B1%9E%E6%80%A7) Attributes** ::: ## Pagination Events | 名称 | 说明 | 类型 | | -------- | ------------------------------------ | ---------------------------------------------------------------------- | | `change` | 分页组件 page 或者 pageSize 改变触发 | `function` | ::: tip 提示 el-pagination 的其他事件的支持写法 如 prev-click，如下示例 ::: 示例： ```html ``` ## Pagination Slots | 插槽名 | 说明 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------- | | `pagination-left`v0.0.2 | 分页器左侧内容 ，`align` 为 `right` 或 `center`（v0.1.28 新增） 时生效。 | | `pagination-right`v0.0.2 | 分页器右侧内容 ，`align` 为 `left` 或 `center`（v0.1.28 新增） 时生效。 | --- --- url: /ecosystem/hooks.md --- # plus-pro-components 内置 hooks ## useTable 初始化表格基本数据，配合 [PlusTable](/components/table.html) 组件使用 ```ts import type { Ref } from 'vue' import type { ActionBarButtonsRow } from 'plus-pro-components/es/components/table' import type { PageInfo } from 'plus-pro-components/es/types' /** * 初始化表格基本数据 * */ export declare function useTable[] = any>( _pageInfo: PageInfo | Ref ): { tableData: Ref> pageInfo: Ref<{ page: number pageSize: number }> total: Ref loadingStatus: Ref buttons: import('vue').ShallowRef } ``` 使用示例 ```ts import { useTable } from 'plus-pro-components' interface TableRow { index: number id: number name: string status: string tag: string progress: number } const { tableData, pageInfo, total, buttons, loadingStatus } = useTable() ``` --- --- url: /README.md --- # plus-pro-components docs ## 本地开发命令的区别 | 命令 | 作用 | 备注 | | ---------- | -------------------------------- | ---------------------------- | | pnpm dev | 预览的文档是在线的组件 | | | pnpm debug | 预览的文档是本地最新的组件 | 写作本地最新组件时使用 | | pnpm start | 预览的文档是本地最新打包后的组件 | 测试最新组件打包后效果时使用 | --- --- url: /components/popover.md --- # Popover 弹出框 ## 基础用法 :::demo popover/basic ::: ## 内容可扩展 :::demo popover/expand ::: ## 虚拟触发 :::demo popover/virtual ::: ## 嵌套操作 :::demo popover/nest ::: ## Popover API ## Popover Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | --------------------- | ------------------ | --------- | ------- | -------- | | `visible` | `Popover` 是否显示 | `boolean` | `false` | 否 | | `hasShowBottomButton` | 是否显示底部按钮 | `boolean` | `false` | 否 | | ... | ... | ... | ... | ... | `...`表示同时支持所有 [ElPopover Attributes](https://element-plus.org/zh-CN/component/popover.html#attributes) ## Popover Events | 名称 | 说明 | 类型 | | --------- | ---------------- | ----------------------------------------------------- | | `show` | 显示时触发 | `function` | | `confirm` | 点击确定按钮触发 | `function` | | `cancel` | 点击取消按钮触发 | `function` | | ... | ... | ... | `...`表示同时支持所有 [ElPopover Attributes](https://element-plus.org/zh-CN/component/popover.html#events) ## Popover Slots | 插槽名 | 说明 | | ------ | ---- | | ... | ... | `...`表示同时支持所有 [ElPopover Attributes](https://element-plus.org/zh-CN/component/popover.html#slots) --- --- url: /components/radio.md --- # Radio 单选 ## 简介 PlusRadio 是在 el-radio-group 和 el-radio 上做的封装，核心功能点是 radio 再次点击可以取消，一般的使用场景是表单默认值是空的情况且非必填，ElementPlus 的组件不支持单选可以取消。 :::tip 提示 要使用 el-radio-button 请直接使用 ElementPlus 官方组件。 ::: ## 基础用法 :::demo radio/basic ::: ## 定义属性 :::demo radio/custom ::: ## Radio API ## Radio Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ----------------------- | -------------------- | -------------------------------------------------------- | ------ | -------- | | `model-value / v-model` | 选中项绑定值 | `string/ number/ boolean` | | 否 | | `options` | radio 的数据源 | `array` [OptionsRow\[\]](/components/type.html#optionsrow) | `[]` | 是 | | `isCancel` | 是否可以取消选中状态 | `boolean` | `true` | 否 | | ... | ... | ... | ... | ... | **`...`表示同时支持所有[ElRadioGroup Attributes](https://element-plus.org/zh-CN/component/radio.html#radiogroup-attributes)，不包含 RadioButton 的属性** :::tip 提示 el-radio 的 props 使用 `options` 中的 `fieldItemProps` 。 ::: ## Radio Events | 名称 | 说明 | 类型 | | -------- | ------------------------- | -------------------------------------------------------------------------------- | | `change` | 单个 value 变化触发的事件 | `function` | ## Exposes | 名称 | 说明 | 类型 | | -------------------- | --------------------- | ------------------------------------------------------------------------- | | `radioGroupInstance` | `el-radio-group` 实例 | `object` | | `radioInstance` | `el-radio`实例 | `object` | --- --- url: /components/search.md --- # Search 搜索 [PlusSearch](/components/search.html) 是在 [PlusForm](/components/form.html) 组件上自定义 `footer` 的基础上构建而来，除下文提到 [PlusSearch](/components/search.html) 特有的属性和方法外，同时支持 [PlusForm](/components/form.html) 组件的所有自定义函数和插槽。 ::: warning 注意 表单`v-model`绑定的值尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题。 [参考 reactive 的局限性](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html#limitations-of-reactive) ::: ## 基础用法 :::demo search/basic ::: ## 显示个数 配置 `show-number` 属性为显示个数，默认值 2。 :::demo search/show-number ::: ## 展开收缩隐藏 配置 `hasUnfold` 属性为`false`展开收缩隐藏，同时默认显示所有搜索框。 :::demo search/hide-unfold ::: ## 自定义搜索按钮 使用`search-footer` 自定义搜索按钮. :::demo search/search-footer ::: ## 默认搜索参数 配置 `defaultValues`属性，设置默认搜索参数，当页面**点击重置按钮**时 [PlusSearch](/components/search.html) 组件的`model-value / v-model` 会被设置为 defaultValues。 :::demo search/default-values ::: ## 隐藏 label 表单整体的`hasLabel` 设置为 `false` 时, 隐藏 label。配置[columns](/components/config.html)中的 `hasLabel`可以控制单个表单项的 label 是否显示， 优先级会更高。 :::demo search/hide-label ::: ## 异步数据用法 [PlusColumn](/components/config.html) 配置中的 `options` 支持数组，函数和 Promise。 [PlusColumn](/components/config.html) 配置中的 `fieldProps` 支持对象 object，函数和 Promise。 :::demo search/async ::: ## Search API ## Search Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | -------- | | `model-value / v-model` | 搜索表单绑定值 （尽量使用 ref 定义绑定的值，以避免 reactive 带来的响应式丢失问题） | `object`[FieldValues](/components/type.html#fieldvalues) | | 否 | | `defaultValues` | 点击重置按钮时 赋值给表单 | `object` [FieldValues](/components/type.html#fieldvalues) | `{}` | 否 | | `columns` | 搜索配置信息 | `array` [PlusColumn\[\]](/components/config.html) | `[]` | 否 | | `hasFooter` | 是否需要全部按钮 | `boolean` | `true` | 否 | | `hasReset` | 是否需要底部按钮 `重置` | `boolean` | `true` | 否 | | `hasUnfold` | 是否显示展开收缩按钮， 当 columns 中有效的数据（hideInSearch 不为 true）的长度小于`showNumber` 时自动隐藏 | `boolean` | `true` | 否 | | `searchLoading` | 查询按钮 loading | `boolean` | `false` | 否 | | `searchText` | 查询按钮文字 | `string` | `查询` | 否 | | `resetText` | 重置按钮文字 | `string` | `重置` | 否 | | `retractText`v0.1.16 | 收起按钮文字 | `string` | `收起` | 否 | | `expandText`v0.1.16 | 展开按钮文字 | `string` | `展开` | 否 | | `inline` | 一行内显示 | `boolean` | `true` | 否 | | `showNumber` | 默认显示个数 | `number` | `2` | 否 | | `rowProps` | el-row 属性 | `object`[RowProps](https://element-plus.org/zh-CN/component/layout.html#row-attributes) | `{gutter: 20}` | 否 | | `colProps` | el-col 属性 | `object`[ColProps](https://element-plus.org/zh-CN/component/layout.html#col-attributes) | `{xs: 24,sm: 12,md: 8,lg: 8,xl: 6}` | 否 | | `collapseTransition`v0.1.15 | 是否开启折叠动画 | `boolean` | `true` | 否 | | `collapseDuration`v0.1.15 | 折叠动画持续时长(单位：ms) | `number` | `300` | 否 | | `needValidate`v0.1.15 | 搜索是否需要校验 ，默认不需要校验表单 | `boolean` | `false` | 否 | | `defaultUnfold`v0.1.24 | 默认展开搜索 | `boolean` | `false` | 否 | | ... | ... | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [PlusFrom 方法](/components/form.html) Attributes** 。 ::: ## Search Events | 名称 | 说明 | 类型 | | --------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `search` | 点击查询按钮触发的事件。v0.1.15 版本新增 `needValidate`，开启后校验通过才会触发 | `function` | | `change` | 表单变化触发的事件 | `function` | | `reset` | 点击重置按钮触发的事件 | `function` | | `collapse`v0.0.6 | 点击展开/收起触发的事件 | `function` | ## Search Slots | 插槽名 | 说明 | 作用域插槽参数 | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `footer` | 自定义搜索 按钮组 区域 | `{isShowUnfold,handleReset,handleSearch,handleUnfold,searchLoading}` searchLoading 参数为v0.1.23新增 | | `tooltip-icon`v0.0.5 | tooltip icon | | | `plus-field-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-label-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项 label，组件会自动根据配置项的 prop 生成对应的插槽 | `{prop,label,fieldProps,valueType,column}` | | `plus-extra-*` | [PlusForm](/components/form.html#form-slots)的自定义渲染 el-form-item 下一行额外的内容，组件会自动根据配置项的 prop 生成对应的插槽 | `{column}` | **footer 作用域插槽参数说明** | 作用域插槽参数 | 说明 | 类型 | 默认值 | | -------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `isShowUnfold` | 多余搜索表单展开情况 | `boolean` | `false` | | `handleReset` | 执行重置按钮方法 | `function` | | | `handleSearch` | 执行搜索按钮方法 | `function` /v0.1.15 版本新增 `needValidate`,开启后类型为 `async function` | | | `handleUnfold` | 执行展开按钮方法 | `function` | | ## Exposes | 名称 | 说明 | 类型 | | ------------------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plusFormInstance` | [PlusForm](/components/form.html) 实例 | `object` | | `handleReset` | 执行重置按钮方法 | `function` | | `handleSearch` | 执行搜索按钮方法 | `function` /v0.1.15 版本新增 `needValidate`,开启后类型为 `async function` | | `handleUnfold` | 执行展开按钮方法 | `function` | ::: tip 提示 拿到 plusFormInstance 中的 formInstance 可以支持所有[PlusFrom 方法](/components/form.html)， 如 `validate`,`validateField`等 ::: --- --- url: /components/sidebar.md --- # Sidebar 侧边栏 ## 简介 PlusSidebar 侧边栏，根据路由信息支持多级展示，可自定义展示。 ## 基础用法 :::demo sidebar/basic ::: ## 横向用法 :::demo sidebar/horizontal ::: ## 外链 路由信息的`path`给 `/+ 链接` 例： `/https://plus-pro-components.com` 。路由信息配置[ PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) :::demo sidebar/external ::: ## 在菜单中不显示某一级 路由信息的`meta` 中添加 `hideInMenu: true`即可。路由信息配置[ PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) :::demo sidebar/hidden ::: ## 自定义菜单 icon 路由信息的`meta.icon`支持组件，函数和 VNode。可以支持图片 icon，el-icon，Svg icon，Symbol svg icon, Iconfont icon，Font-awesome icon 等几乎所有常见 icon。 路由信息配置[ PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) :::demo sidebar/icon ::: ## 自定义菜单头部区域 自定义菜单头部区域 支持 `renderMenuExtra`渲染函数 和`sidebar-extra`插槽， `renderMenuExtra` 优先级高于 插槽。 :::demo sidebar/extra ::: ## 自定义菜单显示 (renderTitle) :::warning 注意 **render 函数的优先级高于插槽** ::: :::demo sidebar/render-menu-item-title ::: ## 自定义菜单显示 (jsx/tsx) :::demo sidebar/menu-item-title-tsx ::: ## 自定义菜单显示 (插槽) :::warning 注意 **插槽优先级低于 render** ::: :::demo sidebar/menu-item-title-slots ::: ## Sidebar API ## Sidebar Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------- | ------- | -------- | | `routes` | 侧边栏的路由信息 | `array` [PlusRouteRecordRaw\[\]](/components/type.html#plusrouterecordraw) | `[]` | 否 | | `collapse/v-model:collapse` | 侧边栏闭合 | `boolean` | `false` | 否 | | `width` deprecated v0.1.20(使用`css`变量`--plus-sidebar-width` 代替) | 侧边栏不闭合时的宽度 | `number / string` | `200` | 否 | | `renderTitle` | 自定义菜单每项标题显示 | `function` | | 否 | | `renderMenuItem` | 自定义 菜单的 menuItem | `function` | | 否 | | `renderSubMenuItem` | 自定义 菜单的 subMenu | `function` | | 否 | | `renderMenuExtra` | 自定义在菜单头和菜单之间 | `function` | | 否 | | ... | ... | ... | ... | ... | :::tip 提示 **`...`表示同时支持所有 [el-menu](https://element-plus.org/zh-CN/component/menu.html#menu-attributes) Attributes** ::: ## Sidebar Events | 名称 | 说明 | 类型 | | --------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `toggleCollapse` | 侧边栏闭合（开启）时触发 | `function` | | `clickMenuItem`v0.1.23 | 自定义点击菜单每一项的事件，**当此事件存在时原有的点击菜单路由跳转的事件将会失效**。 | `function` | ## Sidebar Slots | 插槽名 | 说明 | 作用域插槽参数 | | -------------------- | ------------------------ | -------------------------------------------------------------------- | | `sidebar-item` | 自定义菜单的 menuItem | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-sub` | 自定义菜单的 subMenu | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-item-title` | 自定义菜单每项标题显示 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | | `sidebar-extra` | 自定义在菜单头和菜单之间 | route [PlusRouteRecordRaw](/components/type.html#plusrouterecordraw) | :::warning 注意 **render 函数的优先级高于插槽** ::: ## Exposes | 名称 | 说明 | 类型 | | --------------------- | -------------- | -------------------------------------------------- | | `collapse` | 侧边栏闭合状态 | `boolean` | | `toggleCollapse` | 切换侧边栏 | `function` | | `plusSidebarInstance` | el-menu 的实例 | `object` | --- --- url: /guide/SSR.md --- # SSR --- --- url: /components/steps-form.md --- # StepsForm 分步表单 StepsForm 组件是 [ElSteps,ElStep](https://element-plus.org/zh-CN/component/steps.html)和 [PlusForm](/components/form.html) 组件的组合，支持 [PlusForm](/components/form.html) 组件的所有自定义函数和插槽， 它的主要用途是引导用户按照流程完成任务的分步导航条， 可根据实际应用场景设定步骤，步骤不得少于 2 步。 ## 基础用法 设置 `active` 属性，接受一个 `Number`，表明步骤，从 1 开始。`data` 是分步表单所需的数据。 :::demo steps-form/basic ::: ## 垂直的分步表单 垂直方向的分步表单。 只需要设置 direction 属性为 vertical 即可。 :::demo steps-form/vertical-stepsform ::: ## 带图标的分步表单 通过 icon 属性来设置图标， 图标的类型可以参考 Icon 组件的文档。 :::demo steps-form/icon-stepsform ::: ## 简洁风格的分步表单 设置 simple 可应用简洁风格，该条件下 align-center / description / direction / space 都将失效。 :::demo steps-form/simple ::: ## 插槽渲染分步表单头部 设置 simple 可应用简洁风格，该条件下 align-center / description / direction / space 都将失效。 :::demo steps-form/slots ::: ## 插槽渲染分步表单每一步内容 v0.1.22 新增 设置 step-\* 可应用自定义插槽渲染每一步内容，\*表示的是步骤数，从 1 开始。 :::demo steps-form/step-slots ::: ## StepsForm API ## StepsForm Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | ------------------------------------- | ---------------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------- | | `model-value / v-model` | 分步表单绑定的第几步值 | `number` | `1` | 否 (v0.1.14 版本前是 `必须`) | | `data` | 分步表单展示的数据 | `array` [PlusStepFromRow\[\]](/components/type.html#plusstepfromrow) | `[]` | 否 (v0.1.14 版本前是 `必须`) | | `submitText` v0.1.14 | 提交按钮文字 | `string` | `提交` | 否 | | `nextText` v0.1.14 | 下一步按钮文字 | `string` | `下一步` | 否 | | `preText` v0.1.14 | 上一步按钮文字 | `string` | `上一步` | 否 | | ... | ... | ... | ... | ... | `...`表示同时支持所有 [ElSteps Attributes](https://element-plus.org/zh-CN/component/steps.html#steps-%E5%B1%9E%E6%80%A7) ## StepsForm Events | 名称 | 说明 | 类型 | | --------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `change` | 表单变化触发的事件 | `function` | | `pre` | 点击`上一步`按钮触发的事件 | `function` | | `next` | 点击`下一步`（`提交`）按钮校验通过触发的事件 | `function` `allValues`参数为v0.1.23新增 | | `submit` v0.1.23 | 点击`提交`按钮触发的事件 | `function` | ## StepsForm Slots | 插槽名 | 说明 | 作用域插槽参数 | | -------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | | step-\* v0.1.22 | 每一步内容的插槽，\*表示的是步骤数，从 1 开始 | `{title,form,description,icon,status}` [PlusStepFromRow](/components/type.html#plusstepfromrow) | | ... | ... | ... | `...`表示同时支持所有 [ElStep](https://element-plus.org/zh-CN/component/steps.html#step-%E6%8F%92%E6%A7%BD) 的其他插槽 如 `icon, title, description ` --- --- url: /components/table.md --- # Table 表格 ## 表格整体设计 ![设计](/table.png "table") ## 基础用法 配置[columns](/components/config.html)表头和`table-data`表格数据。 :::demo table/basic ::: ## 自适应内容区高度 v0.1.17 表格配置 `adaptive` 可实现自适应内容区高度，`adaptive` 的默认值是 `false`，`adaptive` 的类型是 ```ts boolean | { /** 表格距离页面底部的偏移量，默认值为 `20` */ offsetBottom?: number /** 页面 `resize` 时的防抖时间，默认值为 `60` ms */ timeout?: number } ``` ::: warning 注意 表格设置`height`属性后， `adaptive`属性将**不在生效**。 ::: ::: tip 提示 在和 搜索栏一起使用时，可能存在高度未更新情况，请参考[常见问题](/components/QA.html#plustable-设置了-adaptive-属性-在搜索栏没有展开表格内容是可以自适应的-展开后表格高度还是之前的怎么办)。 ::: :::demo table/height-adaptive ::: ## 数据多级显示 [columns](/components/config.html)中的 `prop`支持 `x.y.z`形式的 多（无限）级数据形式。 :::warning 注意 **数据级不宜过多，可能会影响性能**。 ::: :::demo table/multiple-level-display ::: ## 空值时的显示 v0.1.31 \ 获取到的值为空（`null`,`undefined`,`''`）时返回的的默认值，column.formatter 存在时不生效。 :::demo table/empty-value ::: ## 自定义状态 配置项中`valueType`为`select`、`radio`或`checkbox `时， 配置[columns](/components/config.html)中的[options](/components/type.html#optionstype)，表格会自动显示 `value` 对应的`状态`和 `label`。 默认的逻辑是 表格的`tableData`中的`实际值`和 `options` 中 `value` 对比 严格相等的话，会取当前项的 `label` 显示在表格中，想自定义显示逻辑的话，只需配置[columns](/components/config.html) 中 `customGetStatus`即可。 :::demo table/status ::: ## 表格列样式简单修改 配置[columns](/components/config.html)中的 `fieldProps`，不仅会作用于表单单项，也会作用于表格单项。使用 `fieldProps`可以做简单的样式修改，更强大的自定义样式，请使用[自定义表格项](/components/table.html#自定义表格项和表单项-插槽)。 :::demo table/cell-style ::: ## 操作栏 默认不显示。配置[actionBar](/components/type.html#actionbarprops) 即可，`actionBar `配置参考 [ActionBarProps](/components/type.html#actionbarprops)。 `actionBar` 中的`type` 支持 `button`，`icon`和 `link`，对应`element plus` 的 [ElButton](https://element-plus.org/zh-CN/component/button.html)，[ElIcon](https://element-plus.org/zh-CN/component/icon.html) 和 [ElLink ](https://element-plus.org/zh-CN/component/link.html)组件。 操作栏`actionBar` 中`buttons`配置参考 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow)， `buttons`中每项配置 `confirm` 即可实现二次确认，配置 `show` 即可实现权限和动态显示。 :::demo table/action-bar ::: ## 操作栏事件 操作栏除了支持[PlusTable Event](/components/table.html#table-events)中的`clickAction`和`clickActionConfirmCancel`外，v0.1.8版本开始支持自身的事件。 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow)支持以下事件。 | 事件名 | 类型 | 触发说明 | | ---------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onClick`v0.1.8 | [ActionBarButtonsRow\['onClick'\]](/components/type.html#actionbarbuttonsrow) | 点击当前按钮的时触发，可与 PlusTable 的事件 `clickAction` 同时触发；操作需要二次确认时：PlusTable 的事件 `clickAction`会在确认时触发，而当前的 onClick 是在点击时触发； | | `onConfirm`v0.1.8 | [ActionBarButtonsRow\['onConfirm'\]](/components/type.html#actionbarbuttonsrow) | 操作需要二次确认时，点击确认时触发 | | `onCancel`v0.1.8 | [ActionBarButtonsRow\['onCancel'\] ](/components/type.html#actionbarbuttonsrow) | 操作需要二次确认时，点击取消时触发， 可与 PlusTable 的事件 `clickActionConfirmCancel` 同时触发 | :::demo table/action-bar-event ::: ## 操作栏权限控制 小于v0.1.7版本 可使用 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow) 中的 `show` 字段控制。 大于等于v0.1.7版本 可使用 [ActionBarButtonsRow](/components/type.html#actionbarbuttonsrow) 中的 `show` 和 `directives`指令字段控制。[参考 vue 渲染函数自定义指令 ](https://cn.vuejs.org/guide/extras/render-function.html#custom-directives) :::demo table/action-bar-directives ::: ## 操作栏二次确认类型 v0.1.17 版本新增气泡确认框 [ElPopconfirm](https://element-plus.org/zh-CN/component/popconfirm.html) 设置表格属性 `actionBar.confirmType` 为 `popconfirm` 即可生效，示例： `` 操作栏二次确认类型配置`confirmType`默认值为`messageBox`即 [ElMessageBox.confirm](https://element-plus.org/zh-CN/component/message-box.html) :::demo table/action-bar-popconfirm ::: ## 操作栏显示的按钮数量 配置[actionBar](/components/type.html#actionbarprops) `showNumber` 属性，`showNumber`在v0.1.23 版本中新增了函数支持。 :::demo table/show-number ::: ## 标题栏 标题栏默认显示右侧工具栏， 可以使用`title`，`toolbar`插槽定制。不需要的的话配置 ``即可。 :::demo table/title-bar ::: ## 拖动排序行 ::: warning 注意 拖动排序行对应的 [el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 的 props，使用[dragSortableTableColumnProps](/components/table.html#table-attributes) 属性配置。 ::: 配置`drag-sortable`，同时配合`dragSortEnd`使用。 :::demo table/drag-sort ::: ## 列设置拖拽排序列 配置 [TitleBar](/components/type.html#titlebar)中的`columnSetting`中的`dragSort`属性，默认为 `true` 可拖拽。 不需要可以给 `false`: ``。 如下示例， 点击 表格右上角列设置 图标，即可通过列设置拖拽排序列。 :::demo table/drag-sort-column ::: ## 列设置信息保存 v0.1.22 新增 使用[columns](/components/config.html)\[`headerIsChecked`] 字段，配合事件[filterTableHeader](/components/table.html#table-events)使用。 :::demo table/title-bar-filter ::: ## 分页栏 默认不显示，配置`pagination`属性即可。 :::demo table/pagination ::: ## 序号栏 ::: warning 注意 序号栏对应的 [el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 的 props，使用[indexTableColumnProps](/components/table.html#table-attributes) 属性配置。 ::: 默认不显示。配置`hasIndexColumn` 为 `true`即可。 配置`indexContentStyle` 可定制序号栏样式。使用`indexTableColumnProps` 为序号栏配置[el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7)属性。 :::demo table/index-column ::: ## 多选 ::: warning 注意 多选栏对应的 [el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 的 props，使用[selectionTableColumnProps](/components/table.html#table-attributes) 属性配置。 ::: 配置`is-selection`属性为`true`，即可显示表格多选框。默认值`false`。配合 [el-table ](https://element-plus.org/zh-CN/component/table.html#table-%E4%BA%8B%E4%BB%B6)`selection-change` 事件使用。 :::demo table/multiple ::: ## 单选 v0.1.23 ::: warning 注意 单选栏对应的 [el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 的 props，使用[radioTableColumnProps ](/components/table.html#table-attributes) 属性配置。 ::: 配置`is-radio`属性为`true`，即可显示表格单选框。默认值`false` :::demo table/radio ::: ## 展开行 ::: warning 注意 展开行栏对应的[el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 的 props，使用[expandTableColumnProps](/components/table.html#table-attributes) 属性配置。 ::: 配置`has-expand`属性 `true` 可显示展开行，默认值 `false`。配合插槽 `expand` 使用。 :::demo table/expand ::: ## 树形结构 配置`tree-props`树形为`children: 'children'`，数据结构中有 children 即可。 树形懒加载表格还需设置`lazy`，`load`。 ::: warning 注意 数据中 `children`中的`id`和表格`id`不能重复。`row-key`默认为`id`。 ::: :::demo table/tree ::: ## 多级表头 v0.1.7 数据结构比较复杂的时候，可使用多级表头来展现数据的层次关系。 只需要将 [el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 放置于[el-table-column](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) 中，就可以实现组头。 :::demo table/multiple-table-header ::: v0.1.19 新增 在 [columns](/components/config.html) 配置添加 [children](/components/config.html) 属性， 即可实现无限极表头。 :::demo table/multiple-level-header ::: ## 表格显示单项插槽配置 组件提供 `fieldSlots` 对象可以简易配置表格显示单项插槽， `fieldSlots` 的插槽配置是根据表格的 [valueType](/components/config.html#valuetype-可选的显示值) 自动进行匹配的， 如： * `valueType` 是 `img` ，`fieldSlots`的插槽就是给 [ElImage](https://element-plus.org/zh-CN/component/image.html#image-slots)的。 * `valueType` 是 `link`时，`fieldSlots`的插槽就是给 [ElLink](https://element-plus.org/zh-CN/component/link.html#slots)的。 * `valueType` 是 `tag`时，`fieldSlots`的插槽就是给 [ElTag](https://element-plus.org/zh-CN/component/tag.html#slots)的。 * 其他以此类推 要实现更强大的自定义，请使用[自定义表格项](/components/table.html#自定义表格项和表单项-插槽)。 ::: warning 注意 valueType 的值对应的组件不是 element-plus 组件时，`fieldSlots`不生效，或者组件本身没有插槽时也不生效。 ::: :::demo table/field-slots ::: ## 可编辑表格 (整体) ::: warning 注意 表格中表单数据不会主动和表格数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: v0.1.4 更新 更新整体可编辑 表格配置`editable`为`true`即可实现整体可编辑， [columns](/components/config.html)中的 `editable` 优先级会更高。 :::demo table/all-cell-edit ::: ## 可编辑表格 (单行) ::: warning 注意 表格中表单数据不会主动和表格数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: v0.1.6 更新表格数据变更后新数据也可编辑 可编辑和校验单行，也可以控制单行的每一个单元格的编辑状态和校验。核心方法是 调用 `formRefs` 里的`startCellEdit()`方法。 :::demo table/row-edit ::: ## 可编辑表格 (单元格) ::: warning 注意 表格中表单数据不会主动和表格数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: v0.1.6 更新表格数据变更后新数据也可编辑 可编辑和校验单元格。核心方法是 调用 `formRefs` 里的`startCellEdit()`方法。 :::demo table/cell-edit ::: ## 可编辑表格 (手动控制) ::: warning 注意 表格中表单数据不会主动和表格数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: v0.1.6 更新表格数据变更后新数据也可编辑 手动控制表格编辑 :::demo table/hand-edit ::: ## 可编辑表格 (点击单元格) ::: warning 注意 表格中表单数据不会主动和表格数据同步，需要结合 [formChange](/components/table.html#table-events) 事件手动同步。 ::: v0.1.4 表格属性`editable`支持 `boolean`，`'click'` ， `'dblclick'`： * 当值为`true` 时：表格都是编辑状态， * 当值为`false`(默认) 时 ：表格都是显示状态， * 当值为`'click'`(点击) 或 `'dblclick'`(双击) 时 ：全部表格都是显示状态，同时携带编辑 icon，需要点击或双击才能打开编辑状态，当点击`表格外`退出编辑状态，同时触发`edited`事件，当点击`其他单元格`时会退出当前单元格的编辑状态，不会触发`edited`事件。 ::: tip 提示 [PlusColumn](/components/config.html) 配置中的 `editable` 仅支持 `boolean`，优先级高于表格整体的`editable`配置。 ::: :::demo table/click-cell-edit ::: ## 自定义表格项和表单项 ( 插槽 ) :::warning 注意 **插槽 的优先级低于 render，高于数据**。 ::: * 自定义表格项 `PlusTable` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-cell-`name`** ]和 \[ **plus-cell-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-cell-** ] 然后加上 配置项的 `prop`。 ```ts import { PlusColumn } from 'plus-pro-components' const tableConfig: PlusColumn[] = [ { label: '名称', // 自动生成对应的插槽 'plus-cell-name' prop: 'name' }, { label: '状态', // 自动生成对应的插槽 'plus-cell-status' prop: 'status' } ] ``` 插槽作用域中会返回 `scoped` 参数,`scoped` 中 包含 `prop`、`label`、`valueType`和`column`等参数可供使用。 * 自定义表单项 参考[自定义表单项(插槽)](/components/form.html#自定义表单项-插槽) （ 表格中需要开启 `editable`） :::demo table/custom-cell-slot ::: ## 自定义表格项和表单项 (render) :::warning 提示 **render 的优先级高于插槽**。 ::: * 自定义表格项 （格式化表格显示） 使用 render 函数自定义表格项。 `render` 方法需要返回一个 [VNode](https://cn.vuejs.org/guide/extras/render-function.html) 或 `string`，返回一个`string`时可以用来格式化表格显示。 自定义表格项还支持 `renderHTML`方法，需要返回一个 HTML 字符串。**谨慎使用，确保 HTML 字符串可信。** * 自定义表单项 参考[自定义表单项-renderField](/components/form.html#自定义表单项-renderfield) （ 表格中需要开启 `editable`） :::demo table/custom-cell ::: ## 自定义表格项和表单项 (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: * 自定义表格项 `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 render 函数自定义表格项。 * 自定义表单项 参考[自定义表单项-jsx-tsx](/components/form.html#自定义表单项-jsx-tsx) （ 表格中需要开启 `editable`） :::demo table/custom-cell-tsx ::: ## 自定义表格表头 (插槽) :::warning 注意 **插槽 的优先级低于 renderHeader，高于 label**。 ::: `PlusTable` 组件会自动根据配置项的 `prop` 生成对应的插槽，例如下面的配置项，则会自动生成两个名称叫做 \[ **plus-header-`name`** ]和 \[ **plus-header-`status`**] 的两个插槽，插槽的生成规则就是 固定 key 值 \[ **plus-header-** ] 然后加上 配置项的 `prop`。 ```ts import { PlusColumn } from 'plus-pro-components' const tableConfig: PlusColumn[] = [ { label: '名称', // 自动生成对应的插槽 'plus-header-name' prop: 'name' }, { label: '状态', // 自动生成对应的插槽 'plus-header-status' prop: 'status' } ] ``` 插槽作用域中会返回 `scoped` 参数,`scoped` 中 包含 `prop`、`label`、`valueType`和`column`等参数可供使用。 :::demo table/custom-header-slot ::: ## 自定义表格表头 (renderHeader) :::warning 注意 **renderHeader 的优先级高于插槽**。 ::: * 使用 renderHeader 函数自定义表格项。 `renderHeader` 方法需要返回一个 [VNode](https://cn.vuejs.org/guide/extras/render-function.html) 或 `String`。 :::demo table/custom-header ::: ## 自定义表格表头 (jsx/tsx) :::warning 注意 jsx/tsx 的使用需要将 vue 单文件组件的`script`的属性 `lang`设置为`jsx`或者`tsx`，`jsx` 中值使用单花括号`{}`绑定。 ```html ``` ::: `jsx/tsx` 的支持本质是`jsx/tsx`解析出来是`VNode`, 使用 renderHeader 函数自定义表格表头。 :::demo table/custom-header-tsx ::: ## 自定义 icon v0.0.3 组件提供了以下插槽可以自定义 icon | 插槽名 | 说明 | | ---------------------- | ------------------------------- | | `action-bar-more-icon` | 操作栏更多旁边的 icon | | `tooltip-icon` | 表格表头 tooltip icon | | `drag-sort-icon` | 表格拖拽行 和 列设置里拖拽 icon | | `column-settings-icon` | 表格表头 列设置 icon | | `density-icon` | 表格表头 密度 icon | :::demo table/icon-slot ::: ## 自定义表格默认插槽内容 v0.1.24 表格的默认`default`插槽为内置`PlusTableColumn`渲染组件，支持文档中描述的所有功能，由于内置组件功能较多，数据量大时可能会存在性能问题，可自定义表格内容，自定义表格默认插槽内容后，表格任然支持以下功能 * `单选` * `多选` * `序号栏` * `拖拽行` * `展开行` * `操作栏` * `分页` 其他功能不再支持，包括`valueType`，`render*`渲染函数,`plus-*-*`插槽等。 :::demo table/custom-content ::: ## 表格显示格式化 表格显示可通过以下三种方式格式化 | 方式 | 说明 | [PlusColumn](/components/config.html)\[`valueType`]是否生效 | 版本支持 | 示例 | | --------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------ | ---------------------------------------------------------- | | [PlusColumn](/components/config.html)\[`render`]返回一个字符串时 | 完全自定义表格行 | 否 | v0.0.1 | [示例](/components/table.html#自定义表格项和表单项-render) | | [PlusColumn](/components/config.html)\[`fieldSlots`] | 定义[PlusColumn](/components/config.html)\[`valueType`]对应的组件的插槽 | 是 | v0.0.1 | [示例](/components/table.html#表格显示单项插槽配置) | | [PlusColumn](/components/config.html)\[`formatter`] | 仅仅格式化显示的值 | 是 | v0.1.13 | 见下文 | 以下是[PlusColumn](/components/config.html)\[`formatter`] 的示例 v0.1.13 :::demo table/formatter ::: ## 综合表格 :::demo table/advanced ::: ## Table API ## Table Attributes | 名称 | 说明 | 类型 | 默认值 | 是否必须 | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------- | | `columns` | 表格配置信息 | `array` [PlusColumn\[\]](/components/config.html) | `[]` | 是 | | `tableData` | 表格数据 | `array` | `[]` | 是 | | `defaultSize` | 默认密度（size） | `string` | `'default'` | 否 | | `pagination` | 分页参数 （默认 `false` 给参数就显示） | `false` / (`object` [PlusPaginationProps](/components/pagination.html#pagination-attributes) ) | `false` | 否 | | `actionBar` | 操作栏参数 （默认 `false` 给参数就显示） | `false` / (`object`[ActionBarProps](/components/type.html#actionbarprops) ) | `false` | 否 | | `titleBar` | 标题栏 | `boolean`/ (`object`[TitleBar](/components/type.html#titlebar)) | `true` | 否 | | `hasIndexColumn` | 是否需要序号 | `boolean` | `false` | 否 | | `isSelection` | 是否是多选表格 | `boolean` | `false` | 否 | | `isRadio` `v0.1.23 | 是否是单选表格 | `boolean` |`false` | 否 | |`dragSortable` | 表格拖拽配置 （默认`false`给参数就显示） |`false` / (`object`[SortableOptions](http://www.sortablejs.com/options.html) ) | `false` | 否 | |`hasExpand` | 是否需要展开行 |`boolean` |`false` | 否 | |`loadingStatus` | 加载状态 |`boolean` |`false` | 否 | |`height` | 表格高度 |`string` | | 否 | |`editable`v0.1.4 | 表格整体可编辑 | `boolean`/`string` |`false` | 否 | |`headerCellStyle` | 表格表头样式 |`object`[CSSProperties](https://cn.vuejs.org/api/utility-types.html#cssproperties) |`{'background-color': 'var(--el-fill-color-light)'}`| 否 | |`indexContentStyle` | 序号栏样式 | (`object`[CSSProperties](https://cn.vuejs.org/api/utility-types.html#cssproperties) ) /`function` |`{}` | 否 | |`dragSortableTableColumnProps` | 拖拽栏 el-table-column 的 props |`object`[ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) |`{}` | 否 | |`indexTableColumnProps` | 序号栏 el-table-column 的 props |`object`[ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) |`{}` | 否 | |`selectionTableColumnProps` | 选择栏 el-table-column 的 props |`object`[ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) |`{width: 40}` | 否 | |`expandTableColumnProps` | 展开栏 el-table-column 的 props |`object`[ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) |`{}` | 否 | |`radioTableColumnProps`v0.1.23 | 单选栏 el-table-column 的 props |`object`[ElTableColumnProps](https://element-plus.org/zh-CN/component/table.html#table-column-%E5%B1%9E%E6%80%A7) |` | 否 | | `radioProps` v0.1.23 | 单选栏 plus-radio 的 props | `object` [PlusRadioProps](https://plus-pro-components.com/components/radio.html#radio-attributes) | ` | 否 | |`defaultSelectedRadioRow`v0.1.23 | 单选栏默认选择的表格行数据 |`object`\| `ComputedRef` | | 否 | |`adaptive`v0.1.17 | 表格高度自适应内容区域配置 |`boolean`\|`object` | `false` | 否 | |`emptyValue` v0.1.31 | 获取到的值为空（`null`,`undefined`,`''`）时返回的的默认值，优先级低于每一项配置 column 的 `emptyValue`值，column.formatter 存在时不生效 | `string`\|`number\` | | 否 | | ... | ... | ... | ... | ... | **`...`表示同时支持所有[ElTable Attributes](https://element-plus.org/zh-CN/component/table.html#table-%E5%B1%9E%E6%80%A7)** :::tip 提示 el-table 的其他属性写法示例 如 `stripe`,`border`,`fit`等 示例： ```html ``` ::: ## Table Events | 名称 | 说明 | 类型 | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paginationChange` | 分页改变触发 | `function` | | `clickAction` | 点击操作栏触发（需要二次确认的，点击确认时触发） | `function` [ButtonsCallBackParams](/components/type.html#buttonscallbackparams) | | `clickActionConfirmCancel` | 点击操作栏需要二次确认的取消时触发 | `function` [ButtonsCallBackParams](/components/type.html#buttonscallbackparams) | | `dragSortEnd` | 拖拽排序行触发 | `function` | | `formChange` | 表格中有可以编辑的表单项目改变时触发 | `function` [FormChangeCallBackParams](/components/type.html#formchangecallbackparams) | | `edited`v0.1.4 | 表格中点击编辑单元格退出时触发 | `function` | | `filterTableHeader`v0.1.22 | 表格表头列设置改变时触发，eventType 参数解释： check：表头单个 check； allCheck：全选/取消全选 check； drag：拖拽； reset：重置； | `function` | | `radioChange`v0.1.23 | 单选栏改变时触发 | `function` `value`（是否选中）参数为 v0.1.24 新增 | | ... | ... | ... | **`...`表示同时支持所有[ElTable 事件](https://element-plus.org/zh-CN/component/table.html#table-%E4%BA%8B%E4%BB%B6)** ::: tip 提示 el-table 的其他事件写法示例 如 `select`,`select-all`,`row-click`等，如下示例 ::: 示例： > 模板中 ```html ``` > setup 中 ```ts const handleSelect = (selection: any[], row: any) => { console.log(selection, row) } const handleSelectAll = (selection: any[]) => { console.log(selection) } ``` ## Table Slots | 插槽名 | 说明 | 作用域插槽参数 | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `default` v0.1.7 | 默认为内置`PlusTableColumn`渲染组件。 | | | `title` | 表格标题 | | | `toolbar` | 工具栏左侧 | | | `expand` | 展开行 | | | `pagination-left`v0.0.2 | 分页器左侧内容 （默认生效，`align` 属性默认是 `right`） | | | `pagination-right`v0.0.2 | 分页器右侧内容 （`align` 属性是 `left`时生效） | | | `action-bar-more-icon`v0.0.3 | 操作栏更多旁边的 icon | | | `tooltip-icon`v0.0.3 | 表格表头 tooltip icon | | | `drag-sort-icon`v0.0.3 | 表格拖拽行 和 列设置里拖拽 icon | | | `column-settings-icon`v0.0.3 | 表格表头 列设置 icon | | | `density-icon`v0.0.3 | 表格表头 密度 icon | | | `edit-icon`v0.1.4 | 表格处于编辑状态时的 icon | | | `plus-cell-*` | 自定义表格项，组件会自动根据配置项的 prop 生成对应的插槽 | `object` | | `plus-header-*` | 自定义表格项 header，组件会自动根据配置项的 prop 生成对应的插槽 | `object` | | `plus-field-*` | [PlusForm](/components/form.html#form-slots) 的自定义表单项，组件会自动根据配置项的 prop 生成对应的插槽 ，需要开启属性 [PlusColumn\['editable'\]](/components/config.html) | `object` | | `plus-extra-*` | [PlusForm](/components/form.html#form-slots)的自定义渲染 el-form-item 下一行额外的内容，组件会自动根据配置项的 prop 生成对应的插槽，需要开启属性 [PlusColumn\['editable'\]](/components/config.html) | `{column,row}` | | ... | ... | ... | **`...`表示同时支持所有[ElTable 插槽](https://element-plus.org/zh-CN/component/table.html#table-%E6%8F%92%E6%A7%BD)** ::: tip 提示 el-table 的其他插槽 如 `append`,`empty`。 **v0.1.7 开始支持 `default` 插槽。** ::: ## Table Exposes | 名称 | 说明 | 类型 | | --------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `tableInstance` | `el-table`的实例 | `object` `import('element-plus')['TableInstance']` | | `formRefs` | 表格中所有 form 的实例，可以用来控制表格是否可编辑，以及表格表单检验等 | `object` | **拿到 tableInstance 后支持所有[ElTable 方法](https://element-plus.org/zh-CN/component/table.html#table-%E6%96%B9%E6%B3%95)** ::: tip 提示 如 `clearSelection`,`getSelectionRows`等 ::: --- --- url: /api\utils/validate.md --- ## validateRegexUrl 校验链接地址 ```ts /** * @desc 校验链接地址 * @param url * @returns */ declare function validateRegexUrl(url: string): boolean ``` 使用示例 ```ts import { validateRegexUrl } from '@plus-pro-components/utils' validateRegexUrl('https://www.api.com') // true ``` ## validatePhone 检验电话 ```ts /** * @desc 检验电话 * @param phone * @returns */ declare const validatePhone: (phone: string) => boolean ``` 使用示例 ```ts import { validatePhone } from '@plus-pro-components/utils' validatePhone('18888888888') // true ``` ## validateLocalPhone 检验固定电话 ```ts /** * @desc 检验固定电话 * @param localPhone * @returns */ declare const validateLocalPhone: (localPhone: string) => boolean ``` 使用示例 ```ts import { validateLocalPhone } from '@plus-pro-components/utils' validateLocalPhone('010-88568888-6603') // true ``` ## validateEmail 检验邮箱 ```ts /** * @desc 检验邮箱 * @param mail * @returns */ declare const validateEmail: (mail: string) => boolean ``` 使用示例 ```ts import { validateEmail } from '@plus-pro-components/utils' validateEmail('8888@qq.com') // true ``` ## validateExternal 判断是否是可跳转 URL ```ts /** * @desc 判断是否是可跳转URL * @param {string} path * @returns */ declare const validateExternal: (path: string) => boolean ``` 使用示例 ```ts import { validateExternal } from '@plus-pro-components/utils' validateExternal('http://www.api.com') // true ``` --- --- url: /api\utils/storage.md --- ## setStorage 设置 `localStorage` ```ts /** * 设置 localStorage * @returns storage */ declare function setToken(key: string, token: string): string ``` 使用示例 ```ts import { setStorage } from '@plus-pro-components/utils' setStorage('key', { data: { username: 'name' } }) ``` ## getStorage 获取 `localStorage` ```ts /** * 获取 localStorage * @returns storage */ declare function getToken(key: string): string ``` 使用示例 ```ts import { getStorage } from '@plus-pro-components/utils' getStorage('key') // { data: { username: "name" } } ``` ## removeStorage 移除 `localStorage` ```ts /** * 移除storage */ declare function removeToken(key: string): void ``` 使用示例 ```ts import { removeStorage } from '@plus-pro-components/utils' removeStorage('key') ``` ## setToken 设置 token 带 AES 加密 （存储在 `localStorage`） ```ts /** * 设置token 带AES加密 * @returns token */ declare function setToken(key: string, token: string): string ``` 使用示例 ```ts import { setToken } from '@plus-pro-components/utils' setToken('tokenKey', 'token') ``` ## getToken 获取 token 带 AES 解密 （获取的是 `localStorage` 的值） ```ts /** * 获取token 带AES解密 * @returns token */ declare function getToken(key: string): string ``` 使用示例 ```ts import { getToken } from '@plus-pro-components/utils' getToken('tokenKey') // 'token' ``` ## removeToken 移除 token （移除的是 `localStorage` 的值） ```ts /** * 移除token */ declare function removeToken(key: string): void ``` 使用示例 ```ts import { removeToken } from '@plus-pro-components/utils' removeToken('tokenKey') ``` --- --- url: /api\utils/number.md --- ## formatMoney 格式化金钱 ```ts /** * 格式化金钱 ￥12,345,678.00 * @param val * @param format 默认 '￥' * @returns */ declare function formatMoney(val: string | number, format?: string): string ``` 使用示例 ```ts import { formatMoney } from '@plus-pro-components/utils' formatMoney('100') // ￥100.00 ``` ## formatNumber 格式化数字 ```ts /** * 格式化数字 * @param number * @param format 默认格式 '0.00' * @returns */ declare function formatNumber(number: number | string, format?: string): string ``` 使用示例 ```ts import { formatNumber } from '@plus-pro-components/utils' formatNumber('100') // 100.00 ``` ## formatNumberFixed 格式化数字保留几位小数，不会四舍五入 ```ts /** * 格式化数字保留几位小数 * @param value * @param decimal 默认2位小数 * @returns x.xx */ declare function formatNumberFixed(value: string, decimal?: number): string ``` 使用示例 ```ts import { formatNumberFixed } from '@plus-pro-components/utils' formatNumberFixed('100.12555') // 100.12 ``` --- --- url: /api\utils/other.md --- ## getBigLetter 生成大写字母 ```ts /** * @desc 生成大写字母 * @returns */ declare const getBigLetter: () => string[] ``` 使用示例 ```ts import { getBigLetter } from '@plus-pro-components/utils' getBigLetter() // ["A","B","C", "D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z"] ``` ## getSmallLetter 生成小写字母 ```ts /** * @desc 生成小写字母 * @returns */ declare const getSmallLetter: () => string[] ``` 使用示例 ```ts import { getSmallLetter } from '@plus-pro-components/utils' getSmallLetter() // ['a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v','w','x','y','z'] ``` ## WS WebSocket 支持自动重连，心跳检测 ```ts /** * setTimeout 类型 */ type Timeout = ReturnType /** * setInterval 类型 */ type Interval = ReturnType /** * 允许null的泛型 */ type Nullable = T | null type AutoReconnect = { /** *重连尝试次数 默认 3 */ reconnectMaxCount?: number } type Heartbeat = { /** * 心跳信息 默认`ping` */ message: string /** * 心跳间隔时间 默认 `3000` 毫秒 */ interval: number } interface WSOptions { /** * 是否自动重连 默认`true` */ autoReconnect: boolean | AutoReconnect /** * 心跳 默认`false` */ heartbeat: boolean | Heartbeat /** * url 携带的参数 */ query: Record } declare class WS { url: string socket: WebSocket | null reconnectCount: number delay: Nullable timer: Nullable autoReconnect: WSOptions['autoReconnect'] heartbeat: WSOptions['heartbeat'] query: WSOptions['query'] constructor(url?: string, options?: WSOptions) /** * 连接 */ connect(): void /** * 监听连接 */ onOpen(): void /** * 开启心跳 */ startHeartbeat(): void /** * 监听错误 */ onError(): void /** * 关闭连接 */ close(): void /** * 监听消息 * @param callback */ onMessage(callback: (...data: any[]) => any): void /** * 发送消息 * @param data */ send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void } ``` 使用示例 ```ts import { WS } from '@plus-pro-components/utils' const ws = new WS('ws://domain.com') ws.onMessage(data => { console.log(data) }) ``` ## openExe 打开电脑本地软件 ```ts /** * @description 打开电脑本地软件 * @param protocol 本地软件协议， 如 vscode 的协议 `vscode://` * @param event 点击按钮事件， `el-button` 或者原生 `button` * @param timeout 默认`1000`ms，没响应则认为打开失败 */ declare const openExe: (protocol: string, event: Event, timeout?: number) => Promise ``` 使用示例 ```html ``` ```ts import { openExe } from '@plus-pro-components/utils' const url = 'vscode://' const handleClick = async (event: MouseEvent) => { await openExe(url, event) } ``` ## isIOS 是否是 ios ```ts /** * 是否是ios * @returns {boolean} */ declare function isIOS(): boolean ``` 使用示例 ```ts import { isIOS } from '@plus-pro-components/utils' isIOS() // false ``` --- --- url: /api\utils/is.md --- ## isArray 判断是否是数组 ```ts /** * 判断是否是数组 */ declare const isArray: (arg: any) => arg is any[] ``` 使用示例 ```ts import { isArray } from '@plus-pro-components/utils' isArray([]) // true ``` ## isMap 判断是否是 Map ```ts /** * 判断是否是Map * @param val * @returns */ declare const isMap: (val: any) => boolean ``` 使用示例 ```ts import { isMap } from '@plus-pro-components/utils' isMap(new Map()) // true ``` ## isSet 判断是否是 Set ```ts /** * 判断是否是Set * @param val * @returns */ declare const isSet: (val: any) => boolean ``` 使用示例 ```ts import { isSet } from '@plus-pro-components/utils' isSet(new Set()) // true ``` ## isDate 判断是否是 Date ```ts /** * 判断是否是Date * @param val * @returns */ declare const isDate: (val: any) => boolean ``` 使用示例 ```ts import { isDate } from '@plus-pro-components/utils' isDate(new Date()) // true ``` ## isRegExp 判断是否是 Reg ```ts /** * 判断是否是Reg * @param val * @returns */ declare const isRegExp: (val: any) => boolean ``` 使用示例 ```ts import { isRegExp } from '@plus-pro-components/utils' isRegExp(new RegExp()) // true ``` ## isFunction 判断是否是函数 ```ts /** * 判断是否是函数 * @param val * @returns */ declare const isFunction: (val: any) => boolean ``` 使用示例 ```ts import { isFunction } from '@plus-pro-components/utils' const func = () => {} isFunction(func) // true ``` ## isString 判断是否是字符串 ```ts /** * 判断是否是字符串 * @param val * @returns */ declare const isString: (val: any) => boolean ``` 使用示例 ```ts import { isString } from '@plus-pro-components/utils' isString('str') // true ``` ## isSymbol 判断是否是 Symbol ```ts /** * 判断是否是Symbol * @param val * @returns */ declare const isSymbol: (val: any) => boolean ``` 使用示例 ```ts import { isSymbol } from '@plus-pro-components/utils' isSymbol(Symbol('str')) // true ``` ## isObject 判断是否是 object ```ts /** * 判断是否是object * @param val * @returns */ declare const isObject: (val: any) => boolean ``` 使用示例 ```ts import { isObject } from '@plus-pro-components/utils' isObject([]) // true isObject({}) // true isObject(function () {}) // true isObject(null) // false ``` ## isPromise 判断是否是 Promise ```ts /** * 判断是否是Promise * @param val * @returns */ declare const isPromise: (val: any) => boolean ``` 使用示例 ```ts import { isPromise } from '@plus-pro-components/utils' isPromise(function () {}) // false isPromise(new Promise()) // true ``` ## isPlainObject 判断是否是 纯对象 object ```ts /** * 判断是否是 纯对象 object * @param val * @returns */ declare const isPlainObject: (val: any) => boolean ``` 使用示例 ```ts import { isPlainObject } from '@plus-pro-components/utils' isPlainObject({}) // true isPlainObject([]) // false isPlainObject(function () {}) // false isPlainObject(null) // false ``` ## isEmptyObject 是否是空纯对象 ```ts /** * 是否是空对象 * @param val * @returns */ declare const isEmptyObject: (val: any) => boolean ``` 使用示例 ```ts import { isEmptyObject } from '@plus-pro-components/utils' isEmptyObject({}) // true isEmptyObject({ data: 'data' }) // false isEmptyObject([]) // false ``` --- --- url: /api\utils/file.md --- ## download 下载文件 ```ts import type { FileSaverOptions } from 'file-saver' interface Download { (data: T, filename: string, options?: FileSaverOptions): Promise } /** * @description 下载文件 * @param {Blob | string} data 文件 Blob * @param {string} filename 文件名称 * @param {object} options 可选参数 */ declare const download: Download ``` 使用示例 ```ts import { download } from '@plus-pro-components/utils' const handleDownload = async () => { await download('data', 'test.txt') } handleDownload() ``` ## isLegalFile 判断文件类型是否符合预期 ```ts /** * * @desc 限制文件类型 * @param {File|Blob} file 源文件 * "默认限制图"片 * @return 合法文件返回true否则返回false */ declare const isLegalFile: (file: File | Blob, types: string[]) => boolean ``` 使用示例 ```ts import { isLegalFile } from '@plus-pro-components/utils' const file = new File(['data'], 'test.txt', { type: 'text/plain' }) isLegalFile(file, ['.txt', '.cad', '.bom', '.dwg', '.job', '.lib']) // true ``` ## isMaxFileSize 判断文件文件上传大小是否符合预期 ```ts /** * @desc 限制文件上传大小 * @param {File|Blob} file 源文件 * @param {number} fileMaxSize 文件大小单位（MB） * @return 在限制内返回true否则返回false */ declare const isMaxFileSize: (file: File | Blob, fileMaxSize?: number) => boolean ``` 使用示例 ```ts import { isMaxFileSize } from '@plus-pro-components/utils' const file = new File(['data'], 'test.txt', { type: 'text/plain' }) isMaxFileSize(file, 1) // true ``` ## fileToDataURL 读取文件为 DataURL 文件格式 （base64） ```ts /** * * @desc 读取文件为DataURL文件格式 （base64） * @param {file|Blob} file 源文件 * @return 返回DataURL文件 （base64） */ declare const fileToDataURL: (file: File | Blob) => Promise ``` 使用示例 ```ts import { fileToDataURL } from '@plus-pro-components/utils' const file = new File(['data'], 'test.txt', { type: 'text/plain' }) const handleFileToDataURL = async () => { const data = await fileToDataURL(file) // data:text/plain;base64,ZGF0YQ== } handleFileToDataURL() ``` ## fileToText 读取文件为 text 文件格式 ```ts /** * @desc 读取文件为text文件格式 * @param {file} file 源文件 * @return 返回text文件 */ declare const fileToText: (file: File | Blob) => Promise ``` 使用示例 ```ts import { fileToText } from '@plus-pro-components/utils' const file = new File(['hello-data'], 'test.txt', { type: 'text/plain' }) const handleFileToText = async () => { const data = await fileToText(file) // hello-data } handleFileToText() ``` ## loadImage 加载图片 ```ts /** * @desc 加载真实图片，读取成功返回图片真实宽高和图片本身对象 ag: { width: 100,height: 100,image: '' } * @param {string} src 图片地址 * @return `{ width: ,height: , image: }` */ declare const loadImage: (src: string) => Promise<{ width: number height: number image: HTMLImageElement }> ``` 使用示例 ```ts import { loadImage } from '@plus-pro-components/utils' const handleLoadImage = async () => { const url = 'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg' const data = await loadImage(url) // {width: 800, height: 572, image: img} } handleLoadImage() ``` ## isLegalResolutionRatio 判断图片文件的分辨率是否在限定范围之内 ```ts /** * @desc 判断图片文件的分辨率是否在限定范围之内，分辨率不在限定范围之内则抛出异常 * @param {File | Blob} file 源文件 * @param {object} props 文件分辨率的宽和高 ag: props={width:100, height :100} */ declare const isLegalResolutionRatio: ( file: File | Blob, props: { width: number height: number } ) => Promise ``` 使用示例 ```ts import { isLegalResolutionRatio } from '@plus-pro-components/utils' const file = new File(['image'], 'test.jpeg', { type: 'image/jpeg' }) const handleIsLegalResolutionRatio = async () => { try { await isLegalResolutionRatio(file, { width: 100, height: 100 }) } catch (error) { console.log(error) // false } } handleIsLegalResolutionRatio() ``` --- --- url: /api\utils/day.md --- ## formatDate 格式化时间 ```ts import type { ConfigType } from 'dayjs' /** * 格式化时间 * @param {string | number | Date | Dayjs | null | undefined} date * @param format 默认YYYY-MM-DD HH:mm:ss * @returns YYYY-MM-DD HH:mm:ss */ declare function formatDate(date?: ConfigType, format?: string): string ``` 使用示例 ```ts import { formatDate } from '@plus-pro-components/utils' formatDate(new Date()) // 2023-01-01 01:01:01 ``` ## formatDateToDay 格式化时间到天 ```ts import type { ConfigType } from 'dayjs' /** * 格式化时间到天 * @param {string | number | Date | Dayjs | null | undefined} date * @returns YYYY-MM-DD */ declare const formatDateToDay: (date: ConfigType) => string ``` 使用示例 ```ts import { formatDateToDay } from '@plus-pro-components/utils' formatDateToDay(new Date()) // 2023-01-01 ``` ## formatDateToMinute 格式化时间到分钟 ```ts import type { ConfigType } from 'dayjs' /** * 格式化时间到分钟 * @param {string | number | Date | Dayjs | null | undefined} date * @returns YYYY-MM-DD HH:mm */ declare const formatDateToMinute: (date: ConfigType) => string ``` 使用示例 ```ts import { formatDateToMinute } from '@plus-pro-components/utils' formatDateToDay(new Date()) // 2023-01-01 01:01 ``` ## diffDate 获取两个 Dayjs 对象的时间差，默认秒。 ```ts import type { QUnitType, OpUnitType, ConfigType } from 'dayjs' /** * 获取两个 Dayjs 对象的时间差，默认秒。 * @param date1 * @param date2 * @param format 默认 'second' * @returns */ declare function diffDate( date1: ConfigType, date2?: ConfigType, format?: QUnitType | OpUnitType ): number | string | undefined ``` 使用示例 ```ts import { diffDate } from '@plus-pro-components/utils' diffDate(new Date(), '2023-01-01 01:01:01') // 18014030 ``` ## diffDateFromCurrent 获取距离当前时间差 返回多少年（月/天/小时/分钟/秒）前 ```ts /** * @desc 获取距离当前时间差 * @param date 时间秒数 * @returns */ declare function diffDateFromCurrent(date: number): string ``` 使用示例 ```ts import { diffDateFromCurrent } from '@plus-pro-components/utils' diffDateFromCurrent(61) // 1秒前 ``` --- --- url: /api\utils/encrypt.md --- ## encrypt AES 加密 ```ts import CryptoJS from 'crypto-js' /** * AES加密 * @param key * @param data * @returns */ declare function encrypt( key: string | CryptoJS.lib.WordArray, data: string | CryptoJS.lib.WordArray ): string ``` 使用示例 ```ts import { encrypt } from '@plus-pro-components/utils' encrypt('key', 'message') // U2FsdGVkX19GcnbMMQplTX7ZrBomhN24tzbA5Nlc1dw= ``` ## decrypt AES 解密 ```ts import CryptoJS from 'crypto-js' /** * AES 解密 * @param key * @param encrypted * @returns */ declare function decrypt( key: string | CryptoJS.lib.WordArray, encrypted: string | CryptoJS.lib.CipherParams ): string ``` 使用示例 ```ts import { decrypt } from '@plus-pro-components/utils' decrypt('key', 'U2FsdGVkX19GcnbMMQplTX7ZrBomhN24tzbA5Nlc1dw=') // message ``` --- --- url: /api\utils/cookie.md --- ## setCookie 设置 cookie ```ts /** * 设置 cookie * @returns */ declare function setCookie(key: string, data: any): string | undefined ``` 使用示例 ```ts import { setCookie } from '@plus-pro-components/utils' setCookie('username', 'name') ``` ## getCookie 获取 cookie ```ts /** * 获取 cookie * @returns */ declare function getCookie(key: string): string | undefined ``` 使用示例 ```ts import { getCookie } from '@plus-pro-components/utils' getCookie('username') // name ``` ## removeCookie 移除 cookie ```ts /** * 移除 cookie */ declare function removeCookie(key: string): void ``` 使用示例 ```ts import { removeCookie } from '@plus-pro-components/utils' removeCookie('username') ``` --- --- url: /donate.md --- ## 简介 [PlusProComponents](/) 是采用 [MIT](https://github.com/plus-pro-components/plus-pro-components?tab=MIT-1-ov-file) 许可的开源项目，个人和企业使用都是完全免费。 项目需要长期的设计、研发和迭代，同时需要服务器和域名等资源的长期支持，为了保证项目的持续良好发展，你可以通过下面方式捐赠，捐赠后即可享受[捐赠者权益](/donate.html#捐赠者权益)。也可[star](https://github.com/plus-pro-components/plus-pro-components)表示鼓励。 ## 捐赠 如果你觉得这个项目帮助到了你，你可以帮作者买一杯果汁表示鼓励 🍹 | 微信 | 支付宝 | | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | | | ## 微信打赏 或者你可以用微信，打赏作者一杯可乐 ## 其他捐赠渠道 [open-collective](https://opencollective.com/plus-pro-components) ## 捐赠者权益 * 你的名称会出现在下面的捐赠名单中 （定期更新） * 你的 issue/PR 将会被优先处理 * 你的 非[PlusProComponents](/)相关问题 将会被处理 * 可添加作者微信 微信号: ，添加微信需备注来意 🌹， 通过后即可享受一对一问题解决服务。 ## 捐赠者名单 非常感谢您们的赞助！ | 赞助人 | 金额 | 赞助人备注 | 作者的回复 | | ---------- | -------- | -------------------- | ----------------------- | | \*伞 | ￥ 50 | 棒\*\*\*\* | 感谢支持 ❤️ | | \*儿 | ￥ 20 | \*\*\*\*很方便 | 感谢支持 ❤️ | | \*蒙 | ￥ 18.8 | 感谢\*\*\*\*无私开源 | 感谢支持 ❤️ | | \*z6 | ￥ 100 | 感谢 \*\*\*\*指导 | 感谢支持 ❤️ | | \*锋 | ￥ 20 | \*\*\*\*感谢开源 | 感谢支持 ❤️ | | \*锋 | ￥ 20 | 多谢 \*\*\*\*指教 | 共同探讨， 感谢支持 ❤️ | | \*娜 | ￥ 2 | \*\*\*\* | 感谢支持 ❤️ | | \*下 | ￥ 8.8 | 谢谢\*\*开源 | 感谢支持 ❤️ | | \*泽 | ￥ 66.66 | \*\*\*\* | 感谢支持 ❤️ | | \*\*连连 | ￥ 9.9 | 喝杯\*\* | 感谢支持 ❤️ | | \*\*连连 | ￥ 9.9 | 大\*\* | 感谢支持 ❤️ | | \*\*连连 | ￥ 9.9 | \*\*\*\* | 感谢支持 ❤️ | | \* | ￥ 18.8 | | 感谢支持 ❤️ | | \*浩 | ￥ 30 | 给\*\*递茶 | 感谢支持 ❤️ | | C\*o | ￥ 101 | 成为你的榜一\*\* | 感谢老铁支持 ❤️ | | F\*s | ￥ 30 | | 感谢支持 ❤️ | | \*天 | ￥ 1 | 分布表单问题\*\* | 感谢支持 ❤️ | | \*橙\*\*GE | ￥ 20 | 真不错的\*\*学习 | 有收获就行，感谢支持 ❤️ | | \*杨 | ￥ 9.9 | 超级好用的\*\*\* | 感谢支持 ❤️ | | \*人 | ￥ 9.9 | pluspro，点\* | 感谢支持 ❤️ | | \*泽 | ￥ 20 | 请\*\*喝奶茶 | 感谢支持 ❤️ | --- --- url: /index.md ---