# Technical Documentation: baidu/amis > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/baidu/amis) ### Overview (README.md)

[文档（国内）](https://aisuda.bce.baidu.com/amis/) | [文档（国外）](https://baidu.github.io/amis/) | [可视化编辑器](https://aisuda.github.io/amis-editor-demo/) | [amis-admin](https://github.com/aisuda/amis-admin) | [爱速搭](https://aisuda.baidu.com/)

如流群：3395342 | 如流群2：5511067|

[](https://codecov.io/gh/baidu/amis)

前端低代码框架，通过 JSON 配置就能生成各种后台页面，极大减少开发成本，甚至可以不需要了解前端。 ## 开发指南以下是参与开发 amis 才需要看的，使用请看前面的文档。 > 如果 github 下载慢可以使用 [gitee](https://gitee.com/baidu/amis) 上的镜像。推荐使用 node 12/14/16。npm 7+，因为用到了 workspaces 功能。 ```bash # 安装项目 npm 依赖，在 node 12 下会有报错但不影响正常使用。 npm i --legacy-peer-deps # 启动项目，等编译结束后通过 http://127.0.0.1:8888/examples/pages/simple 访问。 npm start ``` 如果是开发编辑器，需要访问 `http://127.0.0.1:8888/packages/amis-editor/` ### 测试 > 注意：本地修改代码后，执行测试用例（`npm test --workspaces`）之前需要先执行`npm run build`完成编译，因为 jest 并不支持 TypeScript ```bash # 安装依赖 npm i --legacy-peer-deps # 执行构建 npm run build # 执行测试用例 npm test --workspaces # 测试某个用例 # 为用例名称，比如inputImage npm test --workspace amis -- -t # 运行某个单测文件 ./node_modules/.bin/jest packages/amis/__tests__/renderers/Form/buttonToolBar.test.tsx # 运行某个单测文件里的某个例子 ./node_modules/.bin/jest packages/amis/__tests__/renderers/Form/buttonToolBar.test.tsx -t 'Renderer:button-toolbar' # 查看测试用例覆盖率 npm run coverage # 更新 snapshot npm run update-snapshot # 更新单个 snapshot # 为用例名称，比如inputImage npm run update-snapshot --workspace amis -- -t ``` ### 发布版本 ```bash # 发布内部 registry npm run publish # 发布外网环境 # 先通过一下命令设置版本号 npm run version npm run release ``` ### 如何贡献请使用分支开发，首先创建分支 git checkout -b feat-xxx 开发提交后使用 `git push --set-upstream origin feat-xxx` 创建远程分支。然后通过系统提示的 https://github.com/xxx/amis/pull/new/feat-xxx 链接来提交 PR。请采用 typescript 编写，所有合理的改动、新的公用渲染器、用例或者文档的提交都会被接收。 ## 贡献者

## 低代码平台 amis 只能实现前端低代码，如果需要完整的低代码平台推荐使用[爱速搭](https://aisuda.baidu.com/)。 --- ### Zh CN Index (`docs/zh-CN/index.md`) --- title: 介绍 description: 介绍 type: 0 group: 💡 概念 menuName: 介绍 icon: order: 8 --- ## 什么是 amis amis 是一个低代码前端框架，它使用 JSON 配置来生成页面，可以减少页面开发工作量，极大提升效率。 ## 为什么要做 amis？在经历了十几年的发展后，前端开发变得越来越复杂，门槛也越来越高，要使用当下流行的 UI 组件库，你必须懂 `npm`、`webpack`、`react/vue`，必须熟悉 `ES6` 语法，最好还了解状态管理，比如 `Redux`，如果没接触过函数式编程，光入门都很费劲，而入门之后会发现它还有巨大的 [生态](https://github.com/markerikson/redux-ecosystem-links)，相关的库有 **2347** 个，很多功能相似，挑选成本高。然而前端技术的发展不会停滞，等学完这些后可能会发现大家都用 `Hooks` 了、某个打包工具取代 `Webpack` 了…… 而有时候其实只想做个普通的增删改查界面，用于信息管理，类似下面这种： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 这个界面虽然用 `Bootstrap` 及各种前端 UI 库也能做出个大概，但仔细观察会发现它有大量细节功能，比如： - 可以对数据做筛选 - 有按钮可以刷新数据 - 编辑单行数据 - 批量修改和删除 - 按某列排序 - 可以隐藏某些列 - 可以调整列顺序 - 自动生成顶部查询区域 - 可调整列宽度 - 开启整页内容拖拽排序 - 表格有分页（页数还能同步到地址栏，不过这个例子中关了） - 有数据汇总 - 支持导出 Excel - 「渲染引擎」那列的表头有提示文字 - 鼠标移动到「平台」那列的内容时还有放大镜符号，可以展开查看更多 - 如果往下拖动还有首行冻结来方便查看表头（因为文档页面的限制，这个功能在这里看不出来）全部实现这些需要大量的代码。但可以看到，用 amis 只需要 **157** 行 JSON 配置（其中 47 行只有一个括号），你不需要了解 `React/Vue`、`Webpack`，甚至不需要很了解 `JavaScript`，即便没学过 amis 也能猜到大部分配置的作用，只需要简单配置就能完成所有页面开发。这正是建立 amis 的初衷，我们认为：**对于大部分常用页面，应该使用最简单的方法来实现**，甚至不需要学习前端框架和工具。 ## 用 JSON 写页面有什么好处为了实现用最简单方式来生成大部分页面，amis 的解决方案是基于 [JSON](https://baike.baidu.com/item/JSON) 来配置，它的独特好处是： - **不需要懂前端**：在百度内部，大部分 amis 用户之前从来没写过前端页面，也不会 `JavaScript`，却能做出专业且复杂的后台界面，这是所有其他前端 UI 库都无法做到的； - **不受前端技术更新的影响**：百度内部最老的 amis 页面是 6 年多前创建的，至今还在使用，而当年的 `Angular/Vue/React` 版本现在都废弃了，当年流行的 `Gulp` 也被 `Webpack` 取代了，如果这些页面不是用 amis，现在的维护成本会很高； - **享受 amis 的不断升级**：amis 一直在提升细节交互体验，比如表格首行冻结、下拉框大数据下不卡顿等，之前的 JSON 配置完全不需要修改； - 可以 **完全** 使用 [可视化页面编辑器](https://aisuda.github.io/amis-editor-demo/) 来制作页面：一般前端可视化编辑器只能用来做静态原型，而 amis 可视化编辑器做出的页面是可以直接上线的。 ## amis 的其它亮点 - **提供完整的界面解决方案**：其它 UI 框架必须使用 JavaScript 来组装业务逻辑，而 amis 只需 JSON 配置就能完成完整功能开发，包括数据获取、表单提交及验证等功能，做出来的页面不需要经过二次开发就能直接上线； - **大量内置组件（120+），一站式解决**：其它 UI 框架大部分都只有最通用的组件，如果遇到一些稍微不常用的组件就得自己找第三方，而这些第三方组件往往在展现和交互上不一致，整合起来效果不好，而 amis 则内置大量组件，包括了富文本编辑器、代码编辑器、diff、条件组合、实时日志等业务组件，绝大部分中后台页面开发只需要了解 amis 就足够了； - **支持扩展**：除了低代码模式，还可以通过 [自定义组件](./extend/internal) 来扩充组件，实际上 amis 可以当成普通 UI 库来使用，实现 90% 低代码，10% 代码开发的混合模式，既提升了效率，又不失灵活性； - **容器支持无限级嵌套**：可以通过嵌套来满足各种布局及展现需求； - **经历了长时间的实战考验**：amis 在百度内部得到了广泛使用，**在 6 年多的时间里创建了 5 万页面**，从内容审核到机器管理，从数据分析到模型训练，amis 满足了各种各样的页面需求，最复杂的页面有超过 1 万行 JSON 配置。 ## amis 不适合做什么？使用 JSON 有优点但也有明显缺点，在以下场合并不适合 amis： - **大量定制 UI**：JSON 配置使得 amis 更适合做有大量常见 UI 组件的页面，但对于面向普通客户（toC）的页面，往往追求个性化的视觉效果，这种情况下用 amis 就不合适，实际上绝大部分前端 UI 组件库也都不适合，只能定制开发。 - **极为复杂或特殊的交互**： - 有些复杂的前端功能，比如可视化编辑器，其中有大量定制的拖拽操作，这种需要依赖原生 DOM 实现的功能无法使用 amis。 - 但对于某些交互固定的领域，比如图连线，amis 后续会有专门的组件来实现。 ## 阅读建议 - 如果你是第一次接触 amis，那么请 **务必认真阅读完概念部分**，它会让你对 amis 有个整体的认识 - 如果你已经掌握 amis 基本概念，且有一定的开发经验，需要参考 amis 组件相关文档的同学，那么请移步 [组件文档](../components/page) ## 让我们马上开始吧点击页面底部的下一篇，继续阅读文档。 --- ### Zh CN Components Index (`docs/zh-CN/components/index.md`) --- title: 组件介绍 description: type: 0 group: ⚙ 组件 menuName: 组件介绍 icon: order: 21 --- 从这个章节开始，我们将会介绍 amis 中内置的所有组件的使用方法 --- ### Zh CN Style Index (`docs/zh-CN/style/index.md`) --- title: 快速开始 --- 示例有个[主题编辑器](../../examples/theme)，可以在线实时预览效果。 > 这是 1.1.0 版本中新增的功能在 amis 中自定义样式有四种方式： 1. 使用 CSS 变量动态修改，通过这种方式修改大部分 amis 组件的样式，所有组件都会生效，注意这种方法不支持 IE11。 2. 使用辅助 class，可以对单个组件做定制修改。 3. 自己生成主题 CSS，可以修改所有配置，目前只能通过源码方式，请参考 `scss\themes\cxd.scss` 文件，修改变量后重新编译一个 css，需要注意这种方式在更新 amis 版本的时候最好重新编译，否则就会出现使用旧版 css 的情况，可能导致出错，因此不推荐使用。 4. `wrapper` 组件可以直接写内嵌 `style`。本文主要介绍前两种方法： ## CSS 变量在 page 下可以设置 cssVars 属性，通过它来动态修改 amis 内的 css 变量。 ```schema { "type": "page", "cssVars": { "--text-color": "#CD3632", "--primary": "#CD3632", "--primary-onHover": "#F23F3A", "--primary-onActive": "#BB312D" }, "body": { "type": "form", "body": [ { "type": "input-text", "label": "文本", "name": "text" }, { "type": "input-password", "label": "密码", "name": "password" } ] } } ``` 具体有哪些变量请参考左侧的 [CSS 变量](css-vars) 说明。 ## 辅助 class 辅助 class 参考自[tailwindcss](https://tailwindcss.com/), 做了精简，把一些不常用的剔除了，响应式方面只保留 pc 和手机两种，css 未压缩版本大概是 800K 左右，比 tailwind 要小很多。使用方法： - JS SDK - 引入 sdk 中的文件 `` - React - `import 'amis/lib/helper.css'`; 目前这个文件没有和主题文件合并在一起，用户可以选择性加载。大部分 amis 组件都有 `className` 或者 `xxxClassName` 的配置，比如下面的配置给表单增加了边框、圆角和阴影 ```schema: scope="body" { "type": "form", "panelClassName": "border-solid border-2 border-blue-500 rounded-xl shadow-lg", "body": [ { "type": "input-text", "className": "text-green-700", "label": "文本框", "name": "text" }, { "type": "input-password", "label": "密码", "name": "password" } ] } ``` 还可以： - 通过 `flex` `flex-shrink-0` 来设置布局方式。 - 通过 `bg-blue-100` `bg-white` 之类的类名设置背景色。 - 通过 `shadow-md` 设置投影。 - 通过 `rounded-xl` 设置圆角。 - 通过 `text-xl`、`font-medium` 设置字体大小粗细。 - 等等。。具体用法请查看左边的文档列表。 --- ### Zh CN Components Form Index (`docs/zh-CN/components/form/index.md`) --- title: Form 表单 description: type: 0 group: ⚙ 组件 menuName: Form 表单 icon: order: 24 --- 表单是 amis 中核心组件之一，主要作用是提交或者展示表单数据。 ## 基本用法最基本的用法是配置 [表单项](./formitem) 和提交接口`api`。如下我们配置姓名和邮箱表单项，并可以填写数据并提交给接口`/api/mock2/form/saveForm`。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-email", "label": "邮箱：" } ] } ``` ## 表单展示 ### 默认模式默认展示模式为文字表单项分行显示 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-email", "label": "邮箱：" } ] } ``` ### 水平模式水平模式，左右摆放，左右比率分配。 ```schema: scope="body" { "type": "form", "title": "水平模式", "mode": "horizontal", "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "required": true }, { "type": "input-password", "name": "password", "label": "密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } ``` 可以配置`horizontal`属性，调整偏移量，格式如下： ``` "horizontal": { "left": 2, "right": 10, "offset": 2 } ``` ```schema: scope="body" { "type": "form", "title": "水平模式", "mode": "horizontal", "horizontal": { "left": 2, "right": 10, "offset": 2 }, "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "required": true }, { "type": "input-password", "name": "password", "label": "密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } ``` 通过上面的配置可以看出来水平布局其实按比率分配的。实际上有时候固定左侧宽度更好看点。 ``` "horizontal": { "leftFixed": true } ``` 也可以直接配置 'xs' | 'sm' | 'md' | 'lg' 来定义左侧 label 的宽度。 ```schema: scope="body" { "type": "form", "title": "水平模式", "mode": "horizontal", "horizontal": { "leftFixed": "sm" }, "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "required": true }, { "type": "input-password", "name": "password", "label": "密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } ``` #### 两端对齐有时表单内容需要两端对齐，可在 horizontal 中增加 justify 配置，注意只对内联控件生效 ```schema: scope="body" { "type": "container", "style": { "width": "300px", }, "body": [ { "type": "form", "title": "两端对齐", "mode": "horizontal", "horizontal": { "justify": true, "left": 3, "right": 9 }, "body": [ { "type": "input-text", "name": "name", "label": "姓名", "required": true }, { "type": "input-text", "name": "name", "label": "班级", "required": true }, { "type": "switch", "name": "status", "inputClassName": "is-inline", "label": "是否在职", "onText": "在职", "offText": "非在职" } ] } ] } ``` #### label 对齐模式水平模式下 `labelAlign` 可以设置标签文本的对齐方式，支持`right`和`left`，默认为`right`。该属性的优先级：表单项 > 表单。 ```schema: scope="body" { "type": "form", "title": "label对齐模式", "mode": "horizontal", "labelAlign": "left", "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "labelAlign": "right", "required": true }, { "type": "input-password", "name": "password", "label": "密码", "required": true } ] } ``` ### 内联模式使用内联模式展现表单项 ```schema: scope="body" { "type": "form", "title": "内联模式", "mode": "inline", "body": [ { "type": "input-email", "name": "email", "label": "邮箱" }, { "type": "input-password", "name": "password" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" }, { "type": "submit", "label": "登录" } ] } ``` ### 自定义 label 宽度水平模式下 `labelWidth` 可以设置标签文本的自定义宽度，默认单位为`px`。该属性的优先级：表单项 > 表单。 ```schema: scope="body" { "type": "form", "title": "label对齐模式", "mode": "horizontal", "labelWidth": 120, "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "labelWidth": 200, "required": true }, { "type": "input-password", "name": "password", "label": "密码", "required": true }, { "type": "input-text", "name": "address", "label": "地址", "mode": "inline" }, { "type": "input-text", "name": "mailCode", "label": "邮编", "mode": "inline", "labelWidth": 80 }, { "type": "radios", "name": "mailCode", "label": "性别", "mode": "row", "options": [ { "label": "Male", "value": "male" }, { "label": "Female", "value": "female" } ] } ] } ``` ### 实现一行展示多个表单项有两种方法，一个是通过 `columnCount` 来控制表单显示几列 ```schema: scope="body" { "type": "form", "title": "内联模式", "columnCount": 2, "body": [ { "type": "input-email", "name": "email", "label": "邮箱", "required": true }, { "type": "input-password", "name": "password", "label": "密码" } ] } ``` 另一个方法是使用 group，它能实现每行显示不同列数，以及不同列的宽度分配情况，可以实现更灵活的控制 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 底部按钮栏 #### 隐藏默认提交按钮 Form 默认会在底部渲染一个提交按钮，用于执行表单的提交行为。你可以通过两种方式去掉这个默认的提交按钮： 1. 配置：`"submitText": ""` 2. 配置：`"actions": []` ```schema: scope="body" [ { "type": "form", "title": "通过 submitText 去掉提交按钮", "submitText": "", "body": [ { "type": "input-text", "name": "email", "label": "邮箱" } ] }, { "type": "form", "title": "通过 actions 去掉提交按钮", "actions": [], "body": [ { "type": "input-text", "name": "email", "label": "邮箱" } ] } ] ``` #### 配置若干自定义按钮同样，你可以通过 actions 属性，配置任意你想要的行为按钮。 ```schema: scope="body" { "type": "form", "title": "表单", "body": [ { "type": "input-text", "name": "email", "label": "邮箱" }, { "type": "input-password", "name": "password", "label": "密码" } ], "actions": [ { "type": "submit", "label": "登录" }, { "type": "action", "actionType": "dialog", "label": "登录须知", "dialog": { "title": "登录须知", "body": "登录须知" } }, { "type": "button", "label": "百度一下", "url": "https://www.baidu.com/" } ] } ``` 请记住，如果想触发表单提交行为，请配置`"actionType": "submit"`或`"type": "submit"`按钮 ### 去掉表单边框通过配置`"wrapWithPanel": false`，可以去掉默认表单边框（包括标题，按钮栏以及边距样式等）。 ```schema: scope="body" { "type": "form", "wrapWithPanel": false, "body": [ { "type": "input-text", "name": "email", "label": "邮箱" }, { "type": "input-password", "name": "password", "label": "密码" } ] } ``` **注意！配置该属性后，`title`和`actions`属性将失效并无法渲染，请在表单内自行配置。** ### 固定底部栏如果表单项较多导致表单过长，而不方便操作底部的按钮栏，可以配置`"affixFooter": true`属性，将底部按钮栏固定在浏览器底部 ## 表单静态展示 > 2.4.0 及以上版本在一些场景，表单提交后需要将填写的内容静态展示 ### 设置初始状态通过配置`static: true`将整个表单设置为静态展示，单个表单项也支持此配置 ```schema: scope="body" { "type": "form", "title": "表单状态切换", "mode": "horizontal", "labelWidth": 150, "id": "allFormStatic", "static": true, "body": [ { "type": "input-text", "name": "var1", "label": "输入框", "value": "text" }, { "type": "input-color", "name": "var2", "label": "颜色选择", "value": "#F0F" }, { "type": "switch", "name": "switch", "label": "开关", "option": "开关说明", "value": true } ], "actions": [] } ``` ### 切换输入态和展示态也支持使用[动作](#动作表)切换表单的输入态和展示态（静态），也可以使用动作对单个表单项进行状态切换可以在[示例页](../../../examples/form/switchDisplay)查看表单项的静态展示方式 ```schema: scope="body" { "type": "form", "title": "表单状态切换", "mode": "horizontal", "labelWidth": 150, "id": "allFormSwitch", "data": { "isStatic": false }, "body": [ { "type": "input-text", "name": "var1", "label": "输入框", "value": "text" }, { "type": "input-color", "name": "var2", "label": "颜色选择", "value": "#F0F" }, { "type": "switch", "name": "switch", "label": "开关", "option": "开关说明", "value": true }, { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "${isStatic ? '编辑' : '提交'}", "level": "primary", "onEvent": { "click": { "actions": [ { "actionType": "setValue", "componentId": "allFormSwitch", "args": { "value": { "isStatic": "${!isStatic}" } } }, { "actionType": "static", "componentId": "allFormSwitch", "expression": "${!isStatic}" }, { "actionType": "nonstatic", "componentId": "allFormSwitch", "expression": "${isStatic}" } ] } } } ] } ], "actions": [] } ``` ## 表单项数据初始化表单可以通过配置`initApi`，实现表单初始化时请求接口，用于展示数据或初始化表单项。 ```schema: scope="body" { "type": "form", "initApi": "/api/mock2/form/initData", "title": "编辑用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-text", "name": "email", "label": "邮箱" } ] } ``` 比如以上这个例子接口返回为 ``` { status: 0, msg: "", data: { name: "Amis Renderer", author: "fex", date: 1615978757, info: "" } } ``` 第一个表单项的 name 配置为 `name`，所以这个表单初始化完毕后展示 `Amis Renderer`。 > 表单项的 value 是不支持表达式，所以不要尝试用 `value: "${xxx}"` 来关联数据。 ### 轮询初始化请求 Form 支持轮询初始化接口，步骤如下： 1. 配置`initApi` 2. 配置 `interval`：单位为毫秒，最小 `1000` ```schema: scope="body" { "type": "form", "initApi": "/api/mock2/page/initData", "interval": 3000, "title": "表单", "body": [ { "type": "input-text", "name": "date", "label": "时间戳" } ] } ``` 如果希望在满足某个条件的情况下停止轮询，配置`stopAutoRefreshWhen`表达式。 ```schema: scope="body" { "type": "form", "initApi": "/api/mock2/page/initData", "interval": 3000, "title": "表单", "stopAutoRefreshWhen": "this.date % 5", "body": [ { "type": "input-text", "name": "date", "label": "时间戳" } ] } ``` ### 静态初始化数据域我们也可以手动设置 form 的数据域来初始化多个表单项值 ```schema: scope="body" { "type": "form", "data": { "name": "rick", "email": "rick@gmail.com" }, "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` 注意这里的 `data` 会进行数据映射，如果想不映射，需要进行转义，比如下面的例子 ```schema: scope="body" { "type": "form", "data": { "name": "\\${rick}", "email": "rick@gmail.com" }, "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` ### 数据格式一致性问题当表单来初始化表单项值时，需要保持数据格式的一致性。如果表单初始化的值与表单项配置的数据格式不符合，而且用户没有再次操作该表单项，而直接提交表单，那么会将当前默认值原封不动的提交给后端，也许会导致不一致性的问题，我们看一个例子： ```schema: scope="body" { "type": "form", "data": { "select": ["a", "c"] }, "body": [ { "label": "选项", "type": "select", "name": "select", "multiple": true, "options": [ { "label":"A", "value":"a" }, { "label":"B", "value":"b" }, { "label":"C", "value":"c" } ] } ] } ``` 上例中， `select` 我们配置了`"multiple": true`，预期中，我们希望选中 `A` 和 `C` 项时，表单项的数据格式为：`"a,c"`，但是我们表单数据域中，`select`默认值为`"value": ["a", "c"]`，并不符合我们当前表单项的数据格式配置，这样会导致两个问题： 1. 有可能不会默认选中 `A` 和 `C` 选项； 2. 当不操作该表单项，直接提交时，预期是：`"a,c"`，但提交给后端的数据为：`["a", "c"]`，导致了不一致性的问题。 > 通过 `initApi` 配置默认值同理，不再赘述因此一定确保默认值与选择器表单项数据格式配置相匹配。 ## 表单提交配置`api`属性，当表单执行提交行为时，会默认将当前表单数据域中的数据使用`post`方式发送给所配置`api` ```schema: scope="body" { "type": "form", "api": "/api/saveForm", "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` 点击提交按钮，会看到发送表单请求，请求数据体为： ```json { "name": "xxx", "email": "xxx@xx.com" } ``` 发送请求默认为 `POST` 方式，会将所有表单项整理成一个对象发送过去。除此之外你可以主动获取以下信息。 - `diff` 只会包含 `diff` 结果 - `prinstine` 原始数据如: ```json { "api": { "method": "post", "url": "/api/xxx/save", "data": { "modified": "$$", "diff": "${diff}", "origin": "${prinstine}" } } } ``` > 如果返回了 `data` 对象，且是对象，会把结果 merge 到表单数据里面。当你需要配置特定的请求方式，请求体，`header`时，使用对象类型 api 配置，并使用数据映射进行数据配置。下面示例我们更改了请求方法为`PUT`，并在原提交数据的基础上添加一个字段`"_from"`。更多用法查看 [API 文档](../../../docs/types/api) 和 [数据映射](../../../docs/concepts/data-mapping)文档 ```schema: scope="body" { "type": "form", "initApi": { "method": "put", "url": "/api/mock2/page/initData", "data": { "&": "$$$$", "_from": "browser" } }, "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` 触发表单提交行为有下面几种方式： 1. 默认的`提交按钮` 2. 为行为按钮配置`"actionType": "submit"` 3. 配置`"type": "submit"`的按钮 ### 轮询提交请求通过设置`asyncApi`，当表单提交发送保存接口后，还会继续轮询请求该接口，默认间隔为`3秒`，直到返回 `finished` 属性为 `true` 才结束。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "asyncApi": "/api/mock2/page/initData", "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` 如果决定结束轮询的标识字段名不是 `finished`，请设置`finishedField`属性，比如：`"finishedField": "is_success"` ## 表单校验一般可以通过在[表单项格式校验](./formitem#%E6%A0%BC%E5%BC%8F%E6%A0%A1%E9%AA%8C)中，配置校验规则完成校验，但是有时候，我们需要组合多个表单项实现一些校验，这时可以通过配置 `rules` 来实现组合校验。例如下例，我们想校验 `a` 和 `b` 表单项不可以同时有值，否则就报错，则可以进行如下配置： ```schema:scope="body" { "type": "form", "api": "/api/form/saveForm", "rules": [ { "rule": "!(data.a && data.b)", "message": "a 和 b 不能同时有值" } ], "body": [ { "type": "input-text", "name": "a", "label": "A" }, { "type": "input-text", "name": "b", "label": "B" } ] } ``` > `rule` 编写使用 [表达式](../../../docs/concepts/expression) ### 组合校验高亮表单项 > 1.6.5 及以上版本默认组合校验的错误信息显示在表单的底部，如果希望可以定位到表单项自己，则可以通过配置 `name` 来高亮错误。 ```schema:scope="body" { "type": "form", "api": "/api/form/saveForm", "rules": [ { "rule": "!(data.a && data.b)", "message": "a 和 b 不能同时有值", "name": ["a", "b"] } ], "body": [ { "type": "input-text", "name": "a", "label": "A" }, { "type": "input-text", "name": "b", "label": "B" } ] } ``` ## 重置表单配置`"type": "reset"`或者`"actionType": "reset"`的按钮，可以实现点击重置表单项值。 ```schema: scope="body" { "type": "form", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ], "actions": [ { "type": "reset", "label": "重置" }, { "type": "submit", "label": "保存" } ] } ``` > **请注意：**这里的重置是将表单数据域重置到**初始状态**，**而不是清空**，如果你配置了初始化接口，那么重置操作是会**将表单项重置至初始化表单项值** ## 表单数据域调试配置`debug:true`可以查看当前表单的数据域数据详情，方便数据映射、表达式等功能调试，如下，你可以修改表单项查看数据域变化。`debugConfig`可以额外配置 debug 区域的相关配置，具体配置请参考[Json 组件属性](../json.md#属性表)。 > 2.2.0 及以上版本支持`debugConfig` ```schema: scope="body" { "type": "form", "title": "用户信息", "debug": true, "debugConfig": { "enableClipboard": true, "displayDataTypes": true }, "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` > 该配置不会展示完整的数据链，只会展示当前表单的数据域 ## 禁用数据链默认表单是可以获取到完整数据链中的数据的，但是该默认行为不适用于所有场景，例如：在 CRUD 的列表项中配置弹框，弹框中有一个表单，则该表单项中所有的同`name`表单项都会根据上层`crud`的行数据进行初始化，如果你是实现编辑的功能那并没有是什么问题，但是如果你是新建功能，那么这将不符合你的预期，你可以手动设置`"canAccessSuperData": false`来关闭该行为 ## 提交后行为表单提交成功后，可以执行一些行为。 ### 重置表单如果想提交表单成功后，重置当前表单至初始状态，可以配置`"resetAfterSubmit": true`。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "resetAfterSubmit": true, "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-email", "label": "邮箱：" } ] } ``` 编辑表单项，点击提交，成功后会发现表单项的值会重置到初始状态，即空 > 注意，如果表单项有默认值，则会将该表单项的值重置至该默认值。 ### 跳转页面配置`redirect`属性，可以指定表单提交成功后要跳转至的页面 ```schema: scope="body" { "type": "form", "initApi": "/api/mock2/page/initData", "redirect": "/user/list", "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] } ``` ### 刷新目标组件配置`reload`属性为其他组件`name`值，可以在表单提交成功之后，刷新指定组件。 ```schema: scope="body" [ { "type": "form", "initApi": "/api/mock2/page/initData", "title": "用户信息", "reload": "my_service", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ] }, { "type": "service", "name": "my_service", "api": "/api/mock2/page/initData", "body": "service初识数据" } ] ``` 上例中`form`提交成功后，会触发`name`为`my_service`的`Service`组件重新请求初始化接口上面示例是一种[组件间联动](../../docs/concepts/linkage#%E7%BB%84%E4%BB%B6%E9%97%B4%E8%81%94%E5%8A%A8) ### 显示提交的返回结果默认情况下表单提交返回结果会写入当前表单的数据域，如果要显示在当前表单，可以直接使用 `static` 类型，比如下面的例子 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "title": "用户信息", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "static", "name": "id", "visibleOn": "typeof data.id !== 'undefined'", "label": "返回 ID" } ] } ``` ### 将提交返回内容发送到其它组件还可以将返回结果发送到其它组件，首先设置另一个表单的 `name`，然后通过 `reload` 配置参数来提交 ```schema: scope="body" [ { "type": "form", "api": "/api/mock2/form/saveForm", "title": "用户信息", "reload": "otherForm?id=${id}", "body": [ { "type": "input-text", "name": "name", "label": "姓名" } ] }, { "type": "form", "name": "otherForm", "title": "返回结果", "actions": [], "body": [ { "type": "static", "name": "id", "label": "返回 ID" } ] } ] ``` ### 将数据域发送给目标组件配置`target`属性为目标组件`name`值，可以在触发提交行为后，将当前表单的数据域发送给目标组件。 ```schema: scope="body" [ { "type": "form", "target": "detailForm", "body": [ { "type": "input-text", "placeholder": "关键字", "name": "keywords" } ] }, { "type": "form", "name": "detailForm", "initApi": "/api/mock2/page/initData?keywords=${keywords}", "body": [ { "label": "名称", "type": "static", "name": "name" }, { "label": "作者", "type": "static", "name": "author" }, { "label": "关键字", "type": "static", "name": "keywords" }, { "label": "请求时间", "type": "static-datetime", "format": "YYYY-MM-DD HH:mm:ss", "name": "date" } ] } ] ``` 第一个表单在提交时，会将它的表单数据域数据发送给`detailForm`表单，触发`detailForm`的初始化接口联动，重新请求接口更新数据域，并更新关键字表单项。上面示例组合使用了 [组件间联动](../../docs/concepts/linkage#%E7%BB%84%E4%BB%B6%E9%97%B4%E8%81%94%E5%8A%A8) 和 [接口联动](../../docs/concepts/linkage#%E6%8E%A5%E5%8F%A3%E8%81%94%E5%8A%A8) ## 持久化保存表单项数据表单默认在重置之后（切换页面、弹框中表单关闭表单），会自动清空掉表单中的所有数据，如果你想持久化保留当前表单项的数据而不清空它，那么通过 Form 配置 `persistData: "xxx"`，指定一个 `key` ，来实现数据持久化保存 > 注意，如果使用在 CRUD 列表中的编辑框内的 Form 中，可以利用数据映射语法，`persistData: "xxx:${id}"`，来为 form 指定一个唯一的 key 如果想提交成功后，清空该缓存，则配置`"clearPersistDataAfterSubmit": true` ### 限制只存储某些 key > 2.3.0 及以上版本如果只想存储部分 key，可以配置 `"persistDataKeys": ["key1", "key2"]`，这样就只有 name 为 key1 和 key2 的表单项数据会持久化 ## 禁用回车提交表单默认情况下回车就会提交，如果想阻止这个行为，可以加上 `preventEnterSubmit` 配置项。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "preventEnterSubmit": true, "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-email", "label": "邮箱：" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | type | `string` | | `"form"` 指定为 Form 渲染器 | | name | `string` | | 设置一个名字后，方便其他组件与其通信 | | mode | `string` | `normal` | 表单展示方式，可以是：`normal`、`horizontal` 或者 `inline` | | horizontal | `Object` | `{"left":2, "right":10, "justify": false}` | 当 mode 为 `horizontal` 时有用，用来控制 label 的展示占比 | | labelAlign | `"right" \| "left"` | `"right"` | 表单项标签对齐方式，默认右对齐，仅在 `mode`为`horizontal` 时生效 | | labelWidth | `number \| string` | | 表单项标签自定义宽度 | | title | `string` | `"表单"` | Form 的标题 | | submitText | `String` | `"提交"` | 默认的提交按钮名称，如果设置成空，则可以把默认按钮去掉。 | | className | `string` | | 外层 Dom 的类名 | | body | Array<[表单项](./formitem) or [SchemaNode](../../docs/types/schemanode) > | | Form 表单项集合 | | actions | Array<[行为按钮](../action)> | | Form 提交按钮，成员为 Action | | messages | `Object` | | 消息提示覆写，默认消息读取的是 API 返回的消息，但是在此可以覆写它。 | | messages.fetchSuccess | `string` | | 获取成功时提示 | | messages.fetchFailed | `string` | | 获取失败时提示 | | messages.saveSuccess | `string` | | 保存成功时提示 | | messages.saveFailed | `string` | | 保存失败时提示 | | messages.validateFailed | `string` | `"依赖的部分字段没有通过验证"` | 表单验证失败时的提示 | | wrapWithPanel | `boolean` | `true` | 是否让 Form 用 panel 包起来，设置为 false 后，actions 将无效。 | | panelClassName | `string` | | 外层 panel 的类名 | | api | [API](../../../docs/types/api) | | Form 用来保存数据的 api。 | | initApi | [API](../../../docs/types/api) | | Form 用来获取初始数据的 api。 | | rules | Array<{rule:string;message:string;name?: string[]}> | | 表单组合校验规则 | | interval | `number` | `3000` | 刷新时间(最低 3000) | | silentPolling | `boolean` | `false` | 配置刷新时是否显示加载动画 | | stopAutoRefreshWhen | `string` | `""` | 通过[表达式](./Types.md#表达式) 来配置停止刷新的条件 | | initAsyncApi | [API](../../../docs/types/api) | | Form 用来获取初始数据的 api,与 initApi 不同的是，会一直轮询请求该接口，直到返回 finished 属性为 true 才结束。 | | initFetch | `boolean` | `true` | 设置了 initApi 或者 initAsyncApi 后，默认会开始就发请求，设置为 false 后就不会一开始就请求接口 | | initFetchOn | `string` | | 用表达式来配置 | | initFinishedField | `string` | `finished` | 设置了 initAsyncApi 后，默认会从返回数据的 data.finished 来判断是否完成，也可以设置成其他的 xxx，就会从 data.xxx 中获取 | | initCheckInterval | `number` | `3000` | 设置了 initAsyncApi 以后，默认拉取的时间间隔 | | asyncApi | [API](../../../docs/types/api) | | 设置此属性后，表单提交发送保存接口后，还会继续轮询请求该接口，直到返回 `finished` 属性为 `true` 才结束。 | | checkInterval | `number` | 3000 | 轮询请求的时间间隔，默认为 3 秒。设置 `asyncApi` 才有效 | | finishedField | `string` | `"finished"` | 如果决定结束的字段名不是 `finished` 请设置此属性，比如 `is_success` | | submitOnChange | `boolean` | `false` | 表单修改即提交 | | submitOnInit | `boolean` | `false` | 初始就提交一次 | | resetAfterSubmit | `boolean` | `false` | 提交后是否重置表单 | | primaryField | `string` | `"id"` | 设置主键 id, 当设置后，检测表单是否完成时（asyncApi），只会携带此数据。 | | target | `string` | | 默认表单提交自己会通过发送 api 保存数据，但是也可以设定另外一个 form 的 name 值，或者另外一个 `CRUD` 模型的 name 值。如果 target 目标是一个 `Form` ，则目标 `Form` 会重新触发 `initApi`，api 可以拿到当前 form 数据。如果目标是一个 `CRUD` 模型，则目标模型会重新触发搜索，参数为当前 Form 数据。当目标是 `window` 时，会把当前表单的数据附带到页面地址上。 | | redirect | `string` | | 设置此属性后，Form 保存成功后，自动跳转到指定页面。支持相对地址，和绝对地址（相对于组内的）。 | | reload | `string` | | 操作完后刷新目标对象。请填写目标组件设置的 name 值，如果填写为 `window` 则让当前页面整体刷新。 | | autoFocus | `boolean` | `false` | 是否自动聚焦。 | | canAccessSuperData | `boolean` | `true` | 指定是否可以自动获取上层的数据并映射到表单项上 | | persistData | `string` | `""` | 指定一个唯一的 key，来配置当前表单是否开启本地缓存 | | persistDataKeys | `string[]` | `""` | 指指定只有哪些 key 缓存 | | clearPersistDataAfterSubmit | `boolean` | `true` | 指定表单提交成功后是否清除本地缓存 | | preventEnterSubmit | `boolean` | `false` | 禁用回车提交表单 | | trimValues | `boolean` | `false` | trim 当前表单项的每一个值 | | promptPageLeave | `boolean` | `false` | form 还没保存，即将离开页面前是否弹框确认。 | | columnCount | `number` | 0 | 表单项显示为几列 | | inheritData | `boolean` | `true` | 默认表单是采用数据链的形式创建个自己的数据域，表单提交的时候只会发送自己这个数据域的数据，如果希望共用上层数据域可以设置这个属性为 false，这样上层数据域的数据不需要在表单中用隐藏域或者显式映射才能发送了。 | | static | `boolean` | | `2.4.0` 整个表单静态方式展示，详情请查看[示例页](../../../examples/form/switchDisplay) | | staticClassName | `string` | | `2.4.0` 表单静态展示时使用的类名 | | closeDialogOnSubmit | `boolean` | | 提交的时候是否关闭弹窗。当 form 里面有且只有一个弹窗的时候，本身提交会触发弹窗关闭，此属性可以关闭此行为 | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 事件名称 | 事件参数 | 说明 | | inited | `responseData: any` 请求的响应数据
`responseStatus: number` 响应状态，0 表示成功
`responseMsg: string`响应消息, `error`表示接口是否成功
`[name]: any` 当前数据域中指定字段的值 | 表单初始化完成事件，不管配置不配置 initApi 都会触发，实际上还会等部分子表单项初始化完成 | | change | `event.data: object` 当前表单数据 | 表单值变化时触发 | | formItemValidateSucc | `event.data: object` 当前表单数据
`event.data.__formName` 表单项名字
`event.data.__formValue` 表单项值 | 表单项校验成功时触发 | | formItemValidateError | `event.data: object` 当前表单数据
`event.data.__formName` 表单项名字
`event.data.__formValue` 表单项值
`event.data.__errors`表单项错误 | 表单项校验失败时触发 | | validateSucc | `event.data: object` 当前表单数据 | 表单校验成功时触发 | | validateError | `event.data: object` 当前表单数据 | 表单校验失败时触发 | | submit | `event.data: object` 当前表单数据 | 点击提交按钮或者触发表单提交动作的时候触发（配置了该事件后将不会触发表单提交时的校验、提交到 api 或者 target 等行为，所有行为需要自己配置） | | submitSucc | `event.data.result: object` api 远程请求成功后返回的结果数据 | 提交成功时触发 | | submitFail | `event.data.error: object` api 远程请求失败后返回的错误信息 | 提交失败时触发 | | initApiFinished | `[name]: any` 当前数据域中指定字段的值
`event.data.__trigger` 触发原因：`init` \| `reload` | asyncApi 远程请求轮训结束 | | asyncApiFinished | `[name]: any` 当前数据域中指定字段的值 | asyncApi 远程请求轮训结束 | ### inited ```schema: scope="body" [ { "type": "form", "initApi": "/api/mock2/form/initData", "title": "初始化表单", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-text", "name": "email", "label": "邮箱" } ], "actions": [], "onEvent": { "inited": { "actions": [ { "actionType": "setValue", "componentId": "init_text", "args": { "value": "responseData: ${event.data.responseData|json},responseStatus: ${event.data.responseStatus},responseMsg: ${event.data.responseMsg}" } } ] } } }, { "type": "input-text", "id": "init_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### change ```schema: scope="body" [ { "type": "form", "title": "尝试修改表单项", "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-text", "name": "email", "label": "邮箱" } ], "actions": [], "onEvent": { "change": { "actions": [ { "actionType": "setValue", "componentId": "change_text", "args": { "value": "${event.data|json}" } } ] } } }, { "type": "input-text", "id": "change_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### formItemValidateSucc 事件上下文 - `event.data` 表单的全部数据 - `event.data.__formName` 表单项名字 - `event.data.__formValue` 表单项值 ```schema: scope="body" [ { "type": "form", "title": "尝试修改表单项", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "validateOnChange": true, "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis@baidu.com", "validateOnChange": true, "required": true, "validations": { "isEmail": true } } ], "onEvent": { "formItemValidateSucc": { "actions": [ { "actionType": "setValue", "componentId": "formitem_validate_succ_text", "args": { "value": "${event.data|json}" } } ] }, "formItemValidateError": { "actions": [ { "actionType": "setValue", "componentId": "formitem_validate_succ_text", "args": { "value": "failed" } } ] } } }, { "type": "input-text", "id": "formitem_validate_succ_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### formItemValidateError 事件上下文 - `event.data` 表单的全部数据 - `event.data.__formName` 表单项名字 - `event.data.__formValue` 表单项值 - `event.data.__errors` 表单项的错误，字符数组示例请参考 `formItemValidateSucc` 的例子 ### validateSucc ```schema: scope="body" [ { "type": "form", "title": "尝试修改表单项", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis@baidu.com", "required": true, "validations": { "isEmail": true } } ], "onEvent": { "validateSucc": { "actions": [ { "actionType": "setValue", "componentId": "validate_succ_text", "args": { "value": "${event.data|json}" } } ] } } }, { "type": "input-text", "id": "validate_succ_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### validateError ```schema: scope="body" [ { "type": "form", "title": "尝试修改表单项", "api": "/api/mock2/form/x", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis", "required": true, "validations": { "isEmail": true } } ], "onEvent": { "validateError": { "actions": [ { "actionType": "setValue", "componentId": "validate_fail_text", "args": { "value": "${event.data|json}" } } ] } } }, { "type": "input-text", "id": "validate_fail_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### submit ```schema: scope="body" [ { "type": "form", "title": "尝试提交表单", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis@baidu.com" } ], "onEvent": { "submit": { "actions": [ { "actionType": "setValue", "componentId": "submit_text", "args": { "value": "${event.data|json}" } } ] } } }, { "type": "input-text", "id": "submit_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### submitSucc ```schema: scope="body" [ { "type": "form", "title": "尝试提交表单", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis@baidu.com" } ], "onEvent": { "submitSucc": { "actions": [ { "actionType": "setValue", "componentId": "submit_succ_text", "args": { "value": "${event.data.result|json}" } } ] } } }, { "type": "input-text", "id": "submit_succ_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### submitFail ```schema: scope="body" [ { "type": "form", "title": "尝试提交表单", "api": "/api/mock2/form/x", "body": [ { "type": "input-text", "name": "name", "label": "姓名", "value": "amis" }, { "type": "input-text", "name": "email", "label": "邮箱", "value": "amis@baidu.com" } ], "onEvent": { "submitFail": { "actions": [ { "actionType": "setValue", "componentId": "submit_fail_text", "args": { "value": "${event.data.error|json}" } } ] } } }, { "type": "input-text", "id": "submit_fail_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ### initApiFinished > 6.13.0 起开始支持此事件 initApi 请求完成后触发，包括初始化过程和后续的重新刷新都会触发可以通过 `event.data.__trigger` 来判断，它的分别是 `init` 和 `reload`。 ```schema: scope="body" [ { "type": "form", "title": "尝试提交表单", "initApi": "/api/mock2/page/initData", "id": "theform", "actions": [ { "label": "Reload", type: "button", onEvent: { click: { actions: [ { actionType: "reload", componentId: "theform" } ] } } } ], "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ], "onEvent": { "initApiFinished": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "context: ${event.data|json} trigger: ${event.data.__trigger}" } } ] } } } ] ``` ### asyncApiFinished ```schema: scope="body" [ { "type": "form", "title": "尝试提交表单", "api": "/api/mock2/form/saveForm", "asyncApi": { "url": "/api/mock2/page/initData", "mockResponse": { "status": 200, "data": { "status": 0, "msg": 'ok', "data": { id: 2, finished: true } } } }, "body": [ { "type": "input-text", "name": "name", "label": "姓名" }, { "type": "input-email", "name": "email", "label": "邮箱" } ], "onEvent": { "asyncApiFinished": { "actions": [ { "actionType": "setValue", "componentId": "async_finished_text", "args": { "value": "${event.data|json}" } } ] } } }, { "type": "input-text", "id": "async_finished_text", "static": true, "name": "tip", "label": "上下文" } ] ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | ---------------- | --------------------------------------------------------------------------------------------------------- | -------------------------- | | validate | `outputVar: string` 校验结果，默认为 validateResult | 校验表单 | | submit | `outputVar: string` 提交结果，默认为 submitResult | 提交表单 | | setValue | `value: object` 更新的表单数据 | 更新数据，对数据进行 merge | | reload | - | 刷新（重新加载） | | reset | - | 重置表单 | | clear | - | 清空表单 | | static | - | 表单切换为静态展示 | | nonstatic | - | 表单切换为普通输入态 | | validateFormItem | `componentId: string` 要校验的表单项的 id;
`outputVar: string` 校验结果，默认为 validateFormItemResult | 校验表单项 | ### validate 校验结果默认缓存在`${event.data.validateResult}`，`true`表示校验成功，`false`表示检验失败。可以通过添加`outputVar`配置来修改缓存的变量。校验结果的结构如下： ```json { // 是否成功。非空表示失败 "error": "依赖的部分字段没有通过验证", // 表单项报错信息。key值为该表单项的name值 "errors": { "email": ["Email 格式不正确"], ... }, // 提交验证的表单数据 "payload": { "name": "amis", "email": "amis@baidu" } } ``` ```schema: scope="body" [ { "type": "button", "label": "校验表单", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "validate", "componentId": "form_validate", "outputVar": "form_validate_result" }, { "actionType": "setValue", "componentId": "validate_info", "args": { "value": "${event.data.form_validate_result|json}" } } ] } } }, { type: 'input-text', name: 'validate_info', id: 'validate_info', label: '校验结果：', static: true }, { "type": "form", "id": "form_validate", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名：", "required": true }, { "name": "email", "type": "input-text", "label": "邮箱：", "required": true, "validations": { "isEmail": true } } ] } ] ``` ### submit 提交结果默认缓存在`${event.data.submitResult}`，可以通过添加`outputVar`配置来修改缓存的变量。提交结果的结构如下： ```json { // 是否成功。是否成功。非空表示失败 "error": "依赖的部分字段没有通过验证", // 错误信息。如果是校验失败，则errors为表单项报错信息，key值为该表单项的name值 "errors": { ... }, // 提交的表单数据 "payload": { "name": "amis", "email": "amis@baidu.com" }, // 提交请求返回的响应结果数据 "responseData": { "id": "1" } } ``` ```schema: scope="body" [ { "type": "button", "label": "提交表单", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "submit", "componentId": "form_submit", "outputVar": "form_submit_result" }, { "actionType": "setValue", "componentId": "submit_info", "args": { "value": "${event.data.form_submit_result|json}" } } ] } } }, { type: 'input-text', name: 'submit_info', id: 'submit_info', label: '提交结果：', static: true }, { "type": "form", "id": "form_submit", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名：", "required": true }, { "name": "email", "type": "input-text", "label": "邮箱：", "required": true, "validations": { "isEmail": true } } ] } ] ``` ### setValue 通过`setValue`更新指定表单的数据。 #### 合并数据默认`setValue`会将新数据与目标组件数据进行合并。 ```schema: scope="body" [ { "type": "button", "label": "修改表单数据", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "setValue", "componentId": "form_setvalue", "args": { "value": { "name": "aisuda", "email": "aisuda@baidu.com" } } } ] } } }, { "type": "form", "id": "form_setvalue", "data": { "name": "amis", "email": "amis@baidu.com" }, "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-text", "label": "邮箱：" } ] } ] ``` #### 覆盖数据可以通过`"dateMergeMode": "override"`来覆盖目标组件数据。 ```schema: scope="body" [ { "type": "button", "label": "修改表单数据", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "setValue", "componentId": "form_setvalue", "args": { "value": { "name": "aisuda" } }, "dataMergeMode": "override" } ] } } }, { "type": "form", "id": "form_setvalue", "data": { "name": "amis", "email": "amis@baidu.com" }, "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-text", "label": "邮箱：" } ] } ] ``` ### reload #### 只做刷新重新发送`initApi`请求，刷新 Form 时，只配置`componentId`目标组件 ID 即可。 ```schema: scope="body" [ { "type": "button", "label": "刷新表单", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "reload", "componentId": "form_reload" } ] } } }, { "type": "form", "id": "form_reload", "debug": true, "initApi": "/api/mock2/form/initData", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "author", "type": "input-text", "label": "作者：" } ] } ] ``` #### 发送数据并刷新刷新 Form 组件时，如果配置了`data`，将发送`data`给目标组件，并将该数据合并到目标组件的数据域中（如果配置`"dataMergeMode": "override"`将覆盖目标组件的数据），然后重新请求数据。 ```schema: scope="body" [ { "type": "button", "label": "刷新Form数据加载请求，并将我的年龄设置为18", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "reload", "componentId": "form_reload2", "data": { age: 18 } } ] } } }, { "type": "form", "id": "form_reload2", "debug": true, "initApi": "/api/mock2/form/initData", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "author", "type": "input-text", "label": "作者：" }, { "name": "age", "type": "input-text", "label": "年龄：" } ] } ] ``` ### reset 通过`reset`将表单数据重置为初始数据，初始数据可以是静态数据或初始化接口返回的数据。 ```schema: scope="body" [ { "type": "button", "label": "重置表单", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "reset", "componentId": "form_reset" } ] } } }, { "type": "form", "id": "form_reset", "initApi": "/api/mock2/form/initData", "body": [ { "type": "alert", "body": "修改表单项的值，然后点击【重置表单】，表单数据将被重置为初始化数据" }, { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "author", "type": "input-text", "label": "作者：" } ] } ] ``` ### clear 通过`clear`来清空表单中的表单项数据，不包含`hidden`类型、未绑定表单项的初始化数据字段。 ```schema: scope="body" [ { "type": "button", "label": "清空表单", className: "mb-2", "onEvent": { "click": { "actions": [ { "actionType": "clear", "componentId": "form_clear" } ] } } }, { "type": "form", "id": "form_clear", "debug": true, "initApi": "/api/mock2/form/initData", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "author", "type": "hidden", "label": "作者：" } ] } ] ``` ### static 和 nonstatic ```schema: scope="body" [ { "type": "button", "label": "静态模式", "className": "mr-2 mb-2", "onEvent": { "click": { "actions": [ { "actionType": "static", "componentId": "form_static" } ] } } }, { "type": "button", "label": "非静态模式", "className": "mr-2 mb-2", "onEvent": { "click": { "actions": [ { "actionType": "nonstatic", "componentId": "form_static" } ] } } }, { "type": "form", "id": "form_static", "title": "表单", "body": [ { "type": "input-text", "name": "text", "label": "输入框", "mode": "horizontal", "value": "text" } ] } ] ``` ### validateFormItem > 3.6.4 及以上版本对单个表单项进行校验，通过配置`actionType: 'validateFormItem'`实现表单项的校验校验结果默认缓存在`${event.data.validateFormItemResult}`中，可以通过添加`outputVar`配置来修改缓存的变量校验结果的结构如下： ```json { // 校验结果，非空表示失败 "error": "错误信息", // 校验的表单项的值 "value": "" } ``` ```schema { type: 'page', title: '更新表单数据', body: [ { type: 'form', title: '表单', wrapWithPanel: false, body: [ { type: 'input-text', label: '必填项', name: 'required', id: 'required', required: true } ] }, { "type": "input-text", "name": "validate_info", "id": "validate_info", "label": "校验结果：", "static": true }, { type: 'button', label: '校验', level: 'primary', className: 'mt-2', onEvent: { click: { actions: [ { actionType: 'validateFormItem', componentId: 'required' }, { "actionType": "setValue", "componentId": "validate_info", "args": { "value": "${event.data.validateFormItemResult|json}" } } ] } } } ] } ``` ### clearError > 6.11.1 及以上版本 > 清除表单校验产生的错误状态 ```schema { type: 'page', title: '清除表单错误', body: [ { type: 'form', title: '表单', id: 'form', body: [ { type: 'input-text', label: '必填项', name: 'required', required: true } ] }, { type: 'button', label: '清除错误', level: 'primary', onEvent: { click: { actions: [ { actionType: 'clearError', componentId: 'form' } ] } } } ] } ``` --- ### Zh CN Components Action (`docs/zh-CN/components/action.md`) --- title: Action 行为按钮 description: type: 0 group: ⚙ 组件 menuName: Action 行为按钮 icon: order: 26 --- Action 行为按钮，是触发页面行为的主要方法之一 ## 基本用法我们这里简单实现一个点击按钮弹框的交互。 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` ## 样式 ### 尺寸配置`size`，显示不同尺寸 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "默认尺寸" }, { "type": "button", "label": "极小", "size": "xs" }, { "type": "button", "label": "小", "size": "sm" }, { "type": "button", "label": "中等", "size": "md" }, { "type": "button", "label": "大", "size": "lg" } ] } ``` ### 主题可以配置`level`或者`primary`，显示不同样式。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "默认" }, { "type": "button", "label": "主要", "level": "primary" }, { "type": "button", "label": "次要", "level": "secondary" }, { "type": "button", "label": "信息", "level": "info" }, { "type": "button", "label": "成功", "level": "success" }, { "type": "button", "label": "警告", "level": "warning" }, { "type": "button", "label": "危险", "level": "danger" }, { "type": "button", "label": "浅色", "level": "light" }, { "type": "button", "label": "深色", "level": "dark" }, { "type": "button", "label": "链接", "level": "link" } ] } ``` ### 图标可以配置`icon`配置项，实现按钮显示图标 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "dialog", "icon": "fa fa-plus", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` icon 也可以是 url 地址，比如 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "dialog", "icon": "https://suda.cdn.bcebos.com/images%2F2021-01%2Fdiamond.svg", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` 如果`label`配置为空字符串，可以只显示`icon` ```schema: scope="body" { "label": "", "type": "button", "actionType": "dialog", "icon": "fa fa-plus", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` ## 操作前确认可以通过配置`confirmText`，实现在任意操作前，弹出提示框确认是否进行该操作。同时可以通过配置 `confirmTitle` 来设置弹窗标题 ```schema: scope="body" { "label": "ajax请求", "type": "button", "actionType": "ajax", "confirmText": "确认要发出这个请求？", "confirmTitle": "炸弹", "api": "/api/mock2/form/saveForm" } ``` ## ajax 请求通过配置`"actionType":"ajax"`和`api`，可以实现 ajax 请求。 ```schema: scope="body" { "label": "ajax请求", "type": "button", "actionType": "ajax", "api": "/api/mock2/form/saveForm" } ``` ### 请求成功后，跳转至某个页面 ##### 配置相对路径，实现单页跳转 ```schema: scope="body" { "label": "ajax请求", "type": "button", "actionType": "ajax", "api": "/api/mock2/form/saveForm", "redirect": "../docs/start/getting-started" } ``` ##### 配置完整路径，直接跳转指定路径 ```schema: scope="body" { "label": "ajax请求", "type": "button", "actionType": "ajax", "api": "/api/mock2/form/saveForm", "redirect": "https://www.baidu.com/" } ``` ### 请求成功后，显示反馈弹框 ```schema: scope="body" { "type": "button", "label": "ajax 反馈弹框", "actionType": "ajax", "api": "/api/mock2/form/saveForm", "feedback": { "title": "操作成功", "body": "${id} 已操作成功" } } ``` 更多内容查看[Dialog 文档](./dialog#feedback-%E5%8F%8D%E9%A6%88%E5%BC%B9%E6%A1%86) ### 请求成功后，刷新目标组件 1. 目标组件需要配置 `name` 属性 2. Action 上添加 `"reload": "xxx"`，`xxx` 为目标组件的 `name` 属性值，如果配置多个组件，`name` 用逗号分隔，另外如果想让 reload 的时候再携带些数据可以类似这样配置 `{"reload": "xxx?a=${a}&b=${b}"}`, 这样不仅让目标组件刷新，同时还会把当前环境中的数据 a 和 b 传递给 xxx. ```schema { "type": "page", "body": [ { "type": "button", "label": "ajax 请求", "actionType": "ajax", "api": "/api/mock2/form/saveForm", "reload": "crud" }, { "type": "divider" }, { "type": "crud", "name": "crud", "api": "/api/mock2/sample?waitSeconds=1", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ] } ``` > 配置 `"reload": "window"` 可刷新当前页面 ### 自定义 toast 文字可以通过配置`messages`，自定义接口返回`toast`信息 ```schema: scope="body" { "type": "button", "label": "ajax 请求", "actionType": "ajax", "api": "/api/mapping", "messages": { "success": "成功了！欧耶", "failed": "失败了呢。。" } } ``` 需要注意如果 api 结果返回了 `msg` 字段，会优先使用 api 的返回。 **属性表** | 属性名 | 类型 | 默认值 | 说明 | | -------- | ---------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | api | [Api](../../docs/types/api) | - | 请求地址，参考 [api](../../docs/types/api) 格式说明。 | | redirect | [模板字符串](../../docs/concepts/template#%E6%A8%A1%E6%9D%BF%E5%AD%97%E7%AC%A6%E4%B8%B2) | - | 指定当前请求结束后跳转的路径，可用 `${xxx}` 取值。 | | feedback | `DialogObject` | - | 如果 ajax 类型的，当 ajax 返回正常后，还能接着弹出一个 dialog 做其他交互。返回的数据可用于这个 dialog 中。格式可参考[Dialog](./Dialog) | | messages | `object` | - | `success`：ajax 操作成功后提示，可以不指定，不指定时以 api 返回为准。`failed`：ajax 操作失败提示。 | ## 下载请求 > 1.4.0 及以上版本通过配置 `"actionType":"download"` 和 `api`，可以实现下载请求，它其实是 `ajax` 的一种特例，自动给 api 加上了 `"responseType": "blob"`。 > 3.5.0 版本开始可以配置 `downloadFileName` 来覆盖下载文件名。注意：即便配置了 `downloadFileName`，api 依然需要返回 `Content-Disposition` 头。 ```schema: scope="body" { "label": "下载", "type": "action", "actionType": "download", "api": "/api/download" } ``` 上面的例子由于环境原因没法测试，需要在返回的 header 中配置 `content-type` 和 `Content-Disposition`，比如 ``` Content-Type: application/pdf Content-Disposition: attachment; filename="download.pdf" ``` 如果接口存在跨域，除了常见的 cors header 外，还需要添加以下 header ``` Access-Control-Expose-Headers: Content-Disposition ``` ## 保存到本地 > 1.10.0 及以上版本和前面的下载接口功能类似，但不需要返回 `Content-Disposition` header，只需要解决跨域问题，主要用于一些简单的场景，比如下载文本 ```schema: scope="body" { "label": "保存", "type": "action", "actionType": "saveAs", "api": "/api/download" } ``` > 这个功能目前还没用到 env 里的 fetcher 方法，不支持 POST 默认会自动取 url 中的文件名，如果没有的话就需要指定，比如 ```schema: scope="body" { "label": "保存", "type": "action", "actionType": "saveAs", "fileName": "下载的文件名", "api": "/api/download" } ``` ## 倒计时主要用于发验证码的场景，通过设置倒计时 `countDown`（单位是秒），让点击按钮后禁用一段时间： > 如果同时使用多个倒计时组件时, 需要额外配置全局唯一的`name`或`id`属性, 避免多个组件之间的计时器冲突 ```schema: scope="body" { "type": "form", "body": [ { "name": "phone", "type": "input-text", "required": true, "label": "手机号", "addOn": { "name": "countdown1", "label": "发送验证码", "type": "button", "countDown": 60, "countDownTpl": "${timeLeft} 秒后重发", "actionType": "ajax", "api": "/api/mock2/form/saveForm?phone=${phone}" } } ] } ``` 同时还能通过 `countDownTpl` 来控制显示的文本，其中 `${timeLeft}` 变量是剩余时间。 ## 跳转链接 ### 单页跳转 ```schema: scope="body" { "label": "进入介绍页", "type": "button", "level": "info", "actionType": "link", "link": "../docs/index" } ``` **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------- | | actionType | `string` | `link` | 单页跳转 | | link | `string` | `link` | 用来指定跳转地址，跟 url 不同的是，这是单页跳转方式，不会渲染浏览器，请指定 amis 平台内的页面。可用 `${xxx}` 取值。 | ### 直接跳转 ```schema: scope="body" { "label": "打开 Baidu", "type": "button", "level": "success", "actionType": "url", "url": "http://www.baidu.com" } ``` **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | --------- | ------- | ------------------------------------------------ | | actionType | `string` | `url` | 页面跳转 | | url | `string` | - | 按钮点击后，会打开指定页面。可用 `${xxx}` 取值。 | | blank | `boolean` | `false` | 如果为 `true` 将在新 tab 页面打开。 | ## 发送邮件 ```schema: scope="body" { "label": "发送邮件", "type": "button", "actionType": "email", "to": "amis@baidu.com", "cc": "baidu@baidu.com", "subject": "这是邮件主题", "body": "这是邮件正文" } ``` ### 异步获取数据 ```schema: scope="body" { "type": "page", "initApi": "/api/mock2/mail/mailInfo", "body": { "label": "发送邮件", "type": "button", "actionType": "email", "to": "${to}", "cc": "${cc}", "subject": "${subject}", "body": "${body}" } } ``` **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | -------- | ------- | -------------------------------- | | actionType | `string` | `email` | 点击后显示一个弹出框 | | to | `string` | - | 收件人邮箱，可用 ${xxx} 取值。 | | cc | `string` | - | 抄送邮箱，可用 ${xxx} 取值。 | | bcc | `string` | - | 匿名抄送邮箱，可用 ${xxx} 取值。 | | subject | `string` | - | 邮件主题，可用 ${xxx} 取值。 | | body | `string` | - | 邮件正文，可用 ${xxx} 取值。 | ## 弹框 ```schema: scope="body" { "label": "Dialog Form", "type": "button", "level": "primary", "actionType": "dialog", "dialog": { "title": "表单设置", "body": { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "text", "label": "文本" } ] } } } ``` ### 弹框结合 reload 刷新下拉框的例子下面是一种典型场景，有个一个下拉框，然后有个按钮能弹框新增数据，新增了之后需要下拉框重新拉取最新列表（这个例子因为没实现新增功能，所以看不出更新，如果看网络请求会发现重新请求了一次）。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "name": "myForm", "body": [ { "type": "select", "name": "group", "label": "分组", "source": "/api/mock2/form/getOptions" }, { "label": "新增分组", "type": "button", "level": "primary", "actionType": "dialog", "reload": "myForm.group", "dialog": { "title": "新增分组", "body": { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "groupName", "label": "分组名" } ] } } } ] } ``` 可以看到 `reload` 是 `myForm.group`，第一个是表单的 name，第二个是下拉框的 name。 **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ------------- | -------------------------- | -------- | --------------------------------------------- | | actionType | `string` | `dialog` | 点击后显示一个弹出框 | | dialog | `string` 或 `DialogObject` | - | 指定弹框内容，格式可参考[Dialog](./dialog) | | nextCondition | `boolean` | - | 可以用来设置下一条数据的条件，默认为 `true`。 | ## 抽屉 ```schema: scope="body" { "label": "Drawer Form", "type": "button", "actionType": "drawer", "drawer": { "title": "表单设置", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=1", "body": [ { "type": "input-text", "name": "text", "label": "文本" } ] } } } ``` **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | -------------------------- | -------- | ------------------------------------------ | | actionType | `string` | `drawer` | 点击后显示一个侧边栏 | | drawer | `string` 或 `DrawerObject` | - | 指定弹框内容，格式可参考[Drawer](./drawer) | ## 复制文本 ```schema: scope="body" { "label": "复制一段文本", "type": "button", "actionType": "copy", "content": "http://www.baidu.com" } ``` 可以通过 `copyFormat` 设置复制的格式，默认是文本 ```schema: scope="body" { "label": "复制一段富文本", "type": "button", "actionType": "copy", "copyFormat": "text/html", "content": "link bold" } ``` **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | ------------------------------------ | ------ | ------------------------------------ | | actionType | `string` | `copy` | 复制一段内容到粘贴板 | | content | [模板](../../docs/concepts/template) | - | 指定复制的内容。可用 `${xxx}` 取值。 | ## 刷新其他组件 **属性表** | 属性名 | 类型 | 默认值 | 说明 | | ---------- | -------- | -------- | --------------------------------------------------------------------------- | | actionType | `string` | `reload` | 刷新目标组件 | | target | `string` | - | 需要刷新的目标组件名字（组件的`name`值，自己配置的），多个请用 `,` 号隔开。 | ## 组件特有的行为类型 ### 表单中表格添加一行该 actionType 为[FormItem-Table](./form/input-table#按钮触发新增行)专用行为 ### 校验表单下面的表单中会优先校验按钮`required`属性包含的表单项，当所有的字段校验完毕后，才会校验表单中固有的项目。需要额外注意的是，当按钮中的 `required` 和对应表单项本身的 `required` 属性冲突时，最终校验方式是`"required": true`。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 重置表单在 form 中，配置`"type": "reset"`的按钮，可以实现重置表单数据的功能 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "username", "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "option": "记住登录" } ], "actions": [ { "type": "reset", "label": "重置" }, { "type": "submit", "label": "提交", "level": "primary" } ] } ``` ### 清空表单在 form 中，配置`"actionType": "clear"`的按钮，可以实现清空表单数据的功能，跟重置不同的是，重置其实是还原到初始值，并不一定是清空。 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "username", "placeholder": "请输入用户名", "label": "用户名", "value": "rick" }, { "type": "input-password", "name": "password", "label": "密码", "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "option": "记住登录" } ], "actions": [ { "type": "button", "actionType": "clear", "label": "清空" }, { "type": "reset", "label": "重置" }, { "type": "submit", "label": "提交", "level": "primary" } ] } ``` ### 重置表单并提交 `actionType` 配置成 `"reset-and-submit"` ### 清空表单并提交 `actionType` 配置成 `"clear-and-submit"` ## 自定义点击事件 > 1.3.0 版本新增功能如果上面的行为不满足需求，还可以通过字符串形式的 `onClick` 来定义点击事件，这个字符串会转成 JavaScript 函数，并支持异步（如果是用 sdk 需要自己编译一个 es2017 版本）。 ```schema: scope="body" { "label": "点击", "type": "button", "onClick": "alert('点击了按钮'); console.log(props);" } ``` amis 会传入两个参数 `event` 和 `props`，`event` 就是 React 的事件，而 `props` 可以拿到这个组件的其他属性，同时还能调用 amis 中的内部方法。 ```schema: scope="body" { "label": "点击", "type": "button", "onClick": "props.onAction(event, {actionType:'dialog', dialog: {title: '弹框', body: '这是代码调用的弹框'}})" } ``` 我们将前面的代码拿出来方便分析： ```javascript // event 和 props 前面提到过，而 onAction 就是 amis 内部的方法，可以用来调用其他 action，需要传递两个参数，一个是 event，另一个就是 action 类型及所需的参数。 props.onAction(event, { actionType: 'dialog', dialog: {title: '弹框', body: '这是代码调用的弹框'} }); ``` 这个函数如果返回 `false` 就会阻止 amis 其他 action 的执行，比如这个例子 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "dialog", "onClick": "alert('点击按钮');", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` 它的行为是先执行 alert，再执行弹框，但如果我们加上一个 `return false`，就会发现后面的 amis 弹框不执行了。 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "dialog", "onClick": "alert('点击按钮'); return false;", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` 如果是在表单项中，还能通过 `props.formStore.setValues();` 来修改其它表单项值 ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "type": "input-text", "name": "email", "label": "邮箱：" }, { "label": "修改姓名", "name": "name", "type": "button", "onClick": "props.formStore.setValues({name: 'amis', email: 'amis@baidu.com'});" } ] } ``` ## 全局键盘快捷键触发 > 1.3.0 版本新增功能可以通过 `hotKey` 属性来配置键盘快捷键触发，比如下面的例子 ```schema: scope="body" { "label": "使用 ⌘+o 或 ctrl+o 来弹框", "type": "button", "hotKey": "command+o,ctrl+o", "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` 除了 ctrl 和 command 还支持 shift、alt。其它键盘特殊按键的命名列表：backspace, tab, clear, enter, return, esc, escape, space, up, down, left, right, home, end, pageup, pagedown, del, delete, f1 - f19, num_0 - num_9, num_multiply, num_add, num_enter, num_subtract, num_decimal, num_divide。 > 注意这个主要用于实现页面级别快捷键，如果要实现回车提交功能，请将 `input-text` 放在 `form` 里，而不是给 button 配一个 `enter` 的快捷键。 ## Action 作为容器组件 > 1.5.0 及以上版本 action 还可以使用 `body` 来渲染其他组件，让那些不支持行为的组件支持点击事件，比如下面的例子 ```schema: scope="body" [{ "type": "action", "body": [{ "type": "color", "value": "#108cee" }], "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } },{ "type": "action", "body": { "type": "image", "src": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, "tooltip": "点击会有弹框", "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } }] ``` 在这种模式下不支持按钮的各种配置项，比如 `label`、`size`、`icon` 等，因为它只作为容器组件，没有展现。 ## 按钮提示通过 `tooltip` 来设置提示 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "link", "link": "../index", "tooltip": "点击链接跳转" } ``` 如果按钮是 disabled，需要使用 `disabledTip` ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "link", "disabled": true, "link": "../index", "disabledTip": "禁用了" } ``` 还可以通过 `tooltipPlacement` 设置弹出位置 ```schema: scope="body" { "label": "弹框", "type": "button", "actionType": "link", "link": "../index", "tooltipPlacement": "right", "tooltip": "点击链接跳转" } ``` ## 通用属性表所有`actionType`都支持的通用配置项 | 属性名 | 类型 | 默认值 | 说明 | | ------------------ | ------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | `string` | `action` | 指定为 Page 渲染器。 | | actionType | `string` | - | 【必填】这是 action 最核心的配置，来指定该 action 的作用类型，支持：`ajax`、`link`、`url`、`drawer`、`dialog`、`confirm`、`cancel`、`prev`、`next`、`copy`、`close`。 | | label | `string` | - | 按钮文本。可用 `${xxx}` 取值。 | | level | `string` | `default` | 按钮样式，支持：`link`、`primary`、`secondary`、`info`、`success`、`warning`、`danger`、`light`、`dark`、`default`。 | | size | `string` | - | 按钮大小，支持：`xs`、`sm`、`md`、`lg`。 | | icon | `string` | - | 设置图标，例如`fa fa-plus`。 | | iconClassName | `string` | - | 给图标上添加类名。 | | rightIcon | `string` | - | 在按钮文本右侧设置图标，例如`fa fa-plus`。 | | rightIconClassName | `string` | - | 给右侧图标上添加类名。 | | active | `boolean` | - | 按钮是否高亮。 | | activeLevel | `string` | - | 按钮高亮时的样式，配置支持同`level`。 | | activeClassName | `string` | `is-active` | 给按钮高亮添加类名。 | | block | `boolean` | - | 用`display:"block"`来显示按钮。 | | confirmText | [模板](../../docs/concepts/template) | - | 当设置后，操作在开始前会询问用户。可用 `${xxx}` 取值。 | | confirmTitle | [模板](../../docs/concepts/template) | - | 确认框标题，前提是 confirmText 有内容，支持模版语法 | | reload | `string` | - | 指定此次操作完后，需要刷新的目标组件名字（组件的`name`值，自己配置的），多个请用 `,` 号隔开。 | | tooltip | `string` | - | 鼠标停留时弹出该段文字，也可以配置对象类型：字段为`title`和`content`。可用 `${xxx}` 取值。 | | disabledTip | `'string' \| 'TooltipObject'` | - | 被禁用后鼠标停留时弹出该段文字，也可以配置对象类型：字段为`title`和`content`。可用 `${xxx}` 取值。 | | tooltipPlacement | `string` | `top` | 如果配置了`tooltip`或者`disabledTip`，指定提示信息位置，可配置`top`、`bottom`、`left`、`right`。 | | close | `boolean` or `string` | - | 当`action`配置在`dialog`或`drawer`的`actions`中时，配置为`true`指定此次操作完后关闭当前`dialog`或`drawer`。当值为字符串，并且是祖先层弹框的名字的时候，会把祖先弹框关闭掉。 | | required | `Array` | - | 配置字符串数组，指定在`form`中进行操作之前，需要指定的字段名的表单项通过验证 | ### TooltipObject `TooltipObject` 为 [tooltip-wrapper](./tooltip) 属性配置，但是不需要配置如下属性 `type`、`body`、`wrapperComponent`、`className`、`inline`。 ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ---------- | -------- | -------------- | | click | - | 点击时触发 | | mouseenter | - | 鼠标移入时触发 | | mouseleave | - | 鼠标移出时触发 | ### click 鼠标点击。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "button", "label": "Button", "onEvent": { "click": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseenter 鼠标移入。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "button", "label": "Button", "onEvent": { "mouseenter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseleave 鼠标移出。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "button", "label": "Button", "onEvent": { "mouseleave": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ## 动作表暂无 --- ### Zh CN Components Alert (`docs/zh-CN/components/alert.md`) --- title: Alert 提示 description: type: 0 group: ⚙ 组件 menuName: Alert 提示 icon: order: 27 --- 用来做文字特殊提示，分为四类：提示类、成功类、警告类和危险类。 ## 基本使用 `level`属性支持 4 种预设样式：`info`, `success`, `warning`, `danger`。 ```schema: scope="body" [ { "type": "alert", "body": "提示类文案", "level": "info", "className": "mb-1" }, { "type": "alert", "title": "提示类标题", "body": "提示类文案", "level": "info", "className": "mb-3" }, { "type": "alert", "body": "成功类文案", "level": "success", "className": "mb-1" }, { "type": "alert", "title": "成功类标题", "body": "成功类文案", "level": "success", "className": "mb-3" }, { "type": "alert", "body": "警告类文案", "level": "warning", "className": "mb-1" }, { "type": "alert", "title": "警告类标题", "body": "警告类文案", "level": "warning", "className": "mb-3" }, { "type": "alert", "body": "危险类文案", "level": "danger", "className": "mb-1" }, { "type": "alert", "title": "危险类标题", "body": "危险类文案", "level": "danger", }, ] ``` ## 图标配置`"showIcon": true`后展示图标让信息更加醒目。可以通过`icon`属性自定义设置 icon 内容，如果`icon`属性为空，则根据`level`值添加默认 icon。 ```schema: scope="body" [ { "type": "alert", "body": "提示类文案", "level": "info", "showIcon": true, "className": "mb-1" }, { "type": "alert", "title": "提示类标题", "body": "提示类文案", "level": "info", "showIcon": true, "className": "mb-3" }, { "type": "alert", "body": "成功类文案", "level": "success", "showIcon": true, "className": "mb-1" }, { "type": "alert", "title": "成功类标题", "body": "成功类文案", "level": "success", "showIcon": true, "className": "mb-3" }, { "type": "alert", "body": "警告类文案", "level": "warning", "showIcon": true, "className": "mb-1" }, { "type": "alert", "title": "警告类标题", "body": "警告类文案", "level": "warning", "showIcon": true, "className": "mb-3" }, { "type": "alert", "body": "危险类文案", "level": "danger", "showIcon": true, "className": "mb-1" }, { "type": "alert", "title": "危险类标题", "body": "危险类文案", "level": "danger", "showIcon": true, "className": "mb-3" }, { "type": "alert", "body": "自定义ICON文案", "showIcon": true, "icon": "info-circle", "className": "mb-1" }, { "type": "alert", "title": "自定义ICON标题", "body": "自定义ICON文案", "showIcon": true, "icon": "fa fa-list" } ] ``` ## level 支持表达式 > 1.6.4 及以上版本修改下面例子的 status 值为 2 就能看到变化 ```schema: { "type": "page", "data": { "status": 1 }, "body": [ { "type": "alert", "level": "${IFS(status===1, 'danger', status===2, 'warning')}", "body": "这是内容区" } ] } ``` 同时 icon 和 showIcon 也都支持表达式 ## 显示关闭按钮配置`"showCloseButton": true`实现显示关闭按钮。 ```schema: scope="body" [ { "type": "alert", "body": "显示关闭按钮的提示", "level": "info", "showCloseButton": true, "showIcon": true, "className": "mb-2" }, { "type": "alert", "title": "可关闭提示", "body": "显示关闭按钮的提示", "level": "success", "showCloseButton": true, "showIcon": true } ] ``` ## 操作区域 > `3.6.0`及以上版本配置`actions`属性，可以添加操作区域。 ```schema: scope="body" [ { "type": "alert", "level": "success", "className": "mb-3", "showIcon": true, "showCloseButton": true, "title": "标题", "body": "创建成功", "actions": [ { "type": "button", "label": "查看详情", "size": "xs", "level": "link", "style": { "position": "relative", "top": "25px", "left": "30px" } } ] }, { "type": "alert", "level": "info", "showIcon": true, "showCloseButton": true, "body": "创建成功", "actions": { "type": "flex", "justify": "flex-start", "alignItems": "flex-start", "direction": "column", "style": {"padding": "6px"}, "items": [ { "type": "button", "label": "详情", "size": "xs", "level": "primary", "style": { "marginBottom": "5px" } }, { "type": "button", "label": "关闭", "size": "xs", "level": "danger" } ] } } ] ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | -------------------- | ----------------------------------------- | --------- | -------------------------------------------------------- | --- | | type | `string` | `"alert"` | 指定为 alert 渲染器 | | title | `string` | | alert标题 | | className | `string` | | 外层 Dom 的类名 | | level | `string` | `info` | 级别，可以是：`info`、`success`、`warning` 或者 `danger` | | body | [`SchemaNode[] \| SchemaNode`](../../docs/types/schemanode) | | 显示内容 | | showCloseButton | `boolean` | `false` | 是否显示关闭按钮 | | closeButtonClassName | `string` | | 关闭按钮的 CSS 类名 | | showIcon | `boolean` | `false` | 是否显示 icon | | icon | `string` | | 自定义 icon | | iconClassName | `string` | | icon 的 CSS 类名 | | actions | [`SchemaNode[] \| SchemaNode`](../../docs/types/schemanode) | | 操作区域 | `3.6.0` | --- ### Zh CN Components Amis (`docs/zh-CN/components/amis.md`) --- title: AMIS 渲染器 description: type: 0 group: ⚙ 组件 menuName: AMIS 渲染器 icon: order: 28 --- 用于渲染数据中的 amis 配置 ## 基本使用只需要设置 schema 或 name，值可以是 JSON 对象或字符串的 JSON ```schema: scope="body" { "type": "amis", "schema": { "type": "tpl", "tpl": "amis render" } } ``` ## 通过 name 绑定动态数据可以用在表单或 CRUD 中，下面示例演示了编辑后实时渲染的效果，因为使用了相同的 name ```schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "title": "实时测试 amis 渲染效果", "body": [ { "type": "group", "body": [ { "type": "editor", "name": "amis", "language": "json", "value": { "label": "弹框", "type": "button", "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } }, { "type": "amis", "name": "amis" } ] } ] } ``` ## 向下传递 props 通过设置 props 向下传递，这个 props 会作为默认值 ```schema: scope="body" { "type": "amis", "props": { "tpl": "amis render" }, "value": { "type": "tpl" } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------ | -------- | -------- | ------------------ | | type | `string` | `"amis"` | 指定为 amis 渲染器 | | name | `string` | | 绑定上下文变量名 | | props | `object` | | 向下传递的 props | --- ### Zh CN Components Anchor Nav (`docs/zh-CN/components/anchor-nav.md`) --- title: AnchorNav 锚点导航 description: type: 0 group: ⚙ 组件 menuName: AnchorNav icon: order: 68 --- 锚点导航容器组件。 ## 基本用法 `6.1.0`及以上版本垂直方向支持配置子节点 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 默认想要显示多少锚点导航配置多少个 `links` 成员即可。 ## 水平导航 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 默认定位到某个区域主要配置`active`属性来实现该效果，共有下面两种方法： #### 配置 href 值 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 配置索引值单个`link`上不要配置`href`属性，配置需要展示的`link`索引值，`0`代表第一个。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------------ | --------------------------------- | ----------------------------------- | -------------------------------------------------------------------------- | | type | `string` | `"anchor-nav"` | 指定为 AnchorNav 渲染器 | | className | `string` | | 外层 Dom 的类名 | | linkClassName | `string` | | 导航 Dom 的类名 | | sectionClassName | `string` | | 锚点区域 Dom 的类名 | | links | `Array` | | links 内容 | | direction | `string` | `"vertical"` | 可以配置导航水平展示还是垂直展示。对应的配置项分别是：vertical、horizontal | | active | `string` | | 需要定位的区域 | | links[x].title | `string` | | 区域标题 | | links[x].href | `string` | | 区域标识 | | links[x].body | [SchemaNode](../types/schemanode) | | 区域内容区，`6.1.0`及以上版本垂直方向支持配置子节点 | | links[x].className | `string` | `"bg-white b-l b-r b-b wrapper-md"` | 区域成员样式 | --- ### Zh CN Components App (`docs/zh-CN/components/app.md`) --- title: App 多页应用 description: type: 0 group: ⚙ 组件 menuName: App 多页应用 icon: order: 99 --- 用于实现多页应用，适合于全屏模式，如果只是局部渲染请不要使用。 ## 基本用法类型定义为 `app`，通过 pages 定义页面，支持层级，支持内嵌 schema，或者通过 schemaApi 远程拉取页面，完整用法请参考 [amis-admin](https://github.com/aisuda/amis-admin) 项目里的代码示例，需要修改 `env`： ```json { "type": "app", "brandName": "应用名称", "pages": [ { "label": "分组1", "children": [ { "label": "父页面", "url": "/parent", "children": [ { "label": "子页面", "url": "pageA", "schema": { "type": "page", "title": "Page A" } } ] } ] } ] ... } ``` ## 属性说明 - `type` 请配置成 `app` - `api` 页面配置接口，如果你想远程拉取页面配置请配置。返回配置路径 `json>data>pages`，具体格式请参考 `pages` 属性。 - `brandName` 应用名称。 - `logo` 支持图片地址，或者 svg。 - `className` css 类名。 - `header` 顶部区域。 - `asideBefore` 页面菜单上前面区域。 - `asideAfter` 页面菜单下前面区域。 - `footer` 页面。 - `pages` `Array<页面配置>`具体的页面配置。通常为数组，数组第一层为分组，一般只需要配置 label 集合，如果你不想分组，直接不配置，真正的页面请在第二层开始配置，即第一层的 children 中。具体的页面配置也支持属性结构，每层有以下配置。 - `label` 菜单名称。 - `icon` 菜单图标，比如：fa fa-file. - `url` 页面路由路径，当路由命中该路径时，启用当前页面。当路径不是 `/` 打头时，会连接父级路径。比如：父级的路径为 `folder`，而此时配置 `pageA`, 那么当页面地址为 `/folder/pageA` 时才会命中此页面。当路径是 `/` 开头如： `/crud/list` 时，则不会拼接父级路径。另外还支持 `/crud/view/:id` 这类带参数的路由，页面中可以通过 `${params.id}` 取到此值。 - `schema` 页面的配置，具体配置请前往 [Page 页面说明](./page) - `schemaApi` 如果想通过接口拉取，请配置。返回路径为 `json>data`。schema 和 schemaApi 只能二选一。 - `link` 如果想配置个外部链接菜单，只需要配置 link 即可。 - `redirect` 跳转，当命中当前页面时，跳转到目标页面。 - `rewrite` 改成渲染其他路径的页面，这个方式页面地址不会发生修改。 - `isDefaultPage` 当你需要自定义 404 页面的时候有用，不要出现多个这样的页面，因为只有第一个才会有用。 - `visible` 有些页面可能不想出现在菜单中，可以配置成 `false`，另外带参数的路由无需配置，直接就是不可见的。 - `className` 菜单类名。 ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | -------- | -------- | --------------------------------------------------- | | init | - | 组件实例被创建并插入 DOM 中时触发。2.4.1 及以上版本 | ## 动作表 | 动作名称 | 动作配置 | 说明 | | -------- | -------------------------- | ---------------- | | reload | - | 刷新（重新加载） | | setValue | `value: object` 更新的数据 | 更新数据 | --- ### Zh CN Components Audio (`docs/zh-CN/components/audio.md`) --- title: Audio 音频 description: type: 0 group: ⚙ 组件 menuName: Audio 音频 icon: order: 28 --- ## 基本使用 ```schema: scope="body" { "type": "audio", "src": "https://amis.bj.bcebos.com/amis/2019-7/1562137295708/chicane-poppiholla-original-radio-edit%20(1).mp3" } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------- | --------- | ------------------------------------------------ | --------------------------------------- | | type | `string` | `"audio"` | 指定为 audio 渲染器 | | className | `string` | | 外层 Dom 的类名 | | inline | `boolean` | true | 是否是内联模式 | | src | `string` | | 音频地址 | | loop | `boolean` | false | 是否循环播放 | | autoPlay | `boolean` | false | 是否自动播放 | | rates | `array` | `[]` | 可配置音频播放倍速如：`[1.0, 1.5, 2.0]` | | controls | `array` | `['rates', 'play', 'time', 'process', 'volume']` | 内部模块定制化 | --- ### Zh CN Components Avatar (`docs/zh-CN/components/avatar.md`) --- title: Avatar 头像 description: type: 0 group: ⚙ 组件 menuName: Avatar 头像 icon: order: 27 --- 用来显示用户头像 ## 基本使用 ```schema: scope="body" { "type": "avatar", "src": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ``` ## 文字 ```schema: scope="body" { "type": "avatar", "text": "AM" } ``` ## 图标通过 icon 设置图标 ```schema: scope="body" { "type": "avatar", "icon": "fa fa-user" } ``` > 如果同时存在 src、text 和 icon，会优先用 src、接着 text、最后 icon ## 动态图片或文字 src、text 都支持变量，可以从上下文中动态获取图片或文字，下面的例子中： - 第一个获取到了，显示正常 - 第二个没获取到，因此降级为显示 icon - 第三个图片没获取到，由于 text 优先级比 icon 高，所以显示 text ```schema { "data": { "myAvatar": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" }, "type": "page", "body": [ { "type": "avatar", "icon": "fa fa-user", "src": "$myAvatar" }, { "type": "avatar", "icon": "fa fa-user", "src": "$other" }, { "type": "avatar", "src": "$other", "icon": "fa fa-user", "text": "avatar" } ] } ``` ## 方形和圆角形可以通过 shape 改成方形或圆角形 ```schema: scope="body" [ { "type": "avatar", "shape": "square", "text": "AM" }, { "type": "avatar", "shape": "rounded", "text": "AM", "style": { "marginLeft": "10px" } } ] ``` ## 大小通过 size 可以控制头像的大小 ```schema: scope="body" [ { "type": "avatar", "size": 'large', "icon": "fa fa-user" }, { "type": "avatar", "size": 'default', "icon": "fa fa-user" }, { "type": "avatar", "size": 'small', "icon": "fa fa-user" }, { "type": "avatar", "size": 60, "src": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" }, { "type": "avatar", "src": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" }, { "type": "avatar", "size": 20, "src": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" }, ] ``` ## 控制字符类型距离左右两侧边界单位像素通过 gap 可以控制字符类型距离左右两侧边界单位像素 ```schema: scope="body" [ { "type": "avatar", "text": 'ejson', "gap": 2 }, { "type": "avatar", "text": "ejson", "gap": 7 } ] ``` ## 图片拉伸方式通过 `fit` 可以控制图片拉伸方式，默认是 `'cover'` ```schema: scope="body" [ { "type": "avatar", "fit": "cover", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg" }, { "type": "avatar", "fit": "fill", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg" }, { "type": "avatar", "fit": "contain", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg" }, { "type": "avatar", "fit": "none", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg" }, { "type": "avatar", "fit": "scale-down", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg" } ] ``` ## 控制图片是否允许拖动通过 draggable 可以控制图片是否允许拖动 ```schema: scope="body" [ { "type": "avatar", "fit": "cover", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg", "draggable": false }, { "type": "avatar", "fit": "cover", "src": "https://suda.cdn.bcebos.com/images/amis/plumeria.jpeg", "draggable": true } ] ``` ## 图片加载失败后，通过 onError 控制是否进行 text、icon 置换 > 如果同时存在 text 和 icon，会优先用 text、接着 icon ```schema: scope="body" { "type": "avatar", "src": "empty", "text": "avatar", "onError": "return true;" }, ``` ## 样式可以通过 style 来控制背景及文字颜色 ```schema: scope="body" { "type": "avatar", "text": "AM", "style": { "background": "#DB3E35", "color": "#FFFFFF" } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------- | ------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | className | `string` | | 外层 dom 的类名 | | style | `object` | | 外层 dom 的样式 | | fit | `'contain'` \| `'cover'` \| `'fill'` \| `'none'` \| `'scale-down'` | `'cover'` | 具体细节可以参考 MDN [文档](https://developer.mozilla.org/zh-CN/docs/Web/CSS/object-fit) | | src | `string` | | 图片地址 | | defaultAvatar | `string` | | 占位图 | | text | `string` | | 文字 | | icon | `string` | `'fa fa-user'` | 图标 | | shape | `'circle'` \| `'square'` \| `'rounded'` | `'circle'` | 形状，有三种 `'circle'` （圆形）、`'square'`（正方形）、`'rounded'`（圆角） | | size | `number` \| `'default'` \| `'normal'` \| `'small'` | `'default'` | `'default' \| 'normal' \| 'small'`三种字符串类型代表不同大小（分别是 48、40、32），也可以直接数字表示 | | gap | `number` | 4 | 控制字符类型距离左右两侧边界单位像素 | | alt | `number` | | 图像无法显示时的替代文本 | | draggable | `boolean` | | 图片是否允许拖动 | | crossOrigin | `'anonymous'` \| `'use-credentials'` \| `''` | | 图片的 `CORS` 属性设置 | | onError | `string` | | 图片加载失败的字符串，这个字符串是一个 New Function 内部执行的字符串，参数是 event（使用 event.nativeEvent 获取原生 dom 事件），这个字符串需要返回 boolean 值。设置 `"return ture;"` 会在图片加载失败后，使用 `text` 或者 `icon` 代表的信息来进行替换。目前图片加载失败默认是不进行置换。注意：图片加载失败，不包括$获取数据为空情况 | ## 事件表 > 6.1.0 及以上版本当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ---------- | -------- | -------------- | | click | - | 点击时触发 | | mouseenter | - | 鼠标移入时触发 | | mouseleave | - | 鼠标移出时触发 | ### click 鼠标点击。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "avatar", "onEvent": { "click": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseenter 鼠标移入。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "avatar", "onEvent": { "mouseenter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseleave 鼠标移出。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "avatar", "onEvent": { "mouseleave": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` --- ### Zh CN Components Badge (`docs/zh-CN/components/badge.md`) --- title: Badge 角标 description: type: 0 group: ⚙ 组件 menuName: Badge icon: order: 30 --- ## 基本用法部分组件可以设置 `badge` 属性来显示角标。 > 1.2.2 及之前版本只支持头像组件 > > 1.2.3 开始支持按钮、链接、模板组件。 ```schema: scope="body" [ { "type": "avatar", "badge": { "mode": "text", "text": 10 } }, { "type": "divider" }, { "type": "action", "label": "按钮", "badge": { "mode": "text", "text": 15 } }, { "type": "divider" }, { "type": "link", "href": "https://www.baidu.com", "body": "百度一下，你就知道", "badge": { "position": "top-right" } }, { "type": "divider" }, { "type": "tpl", "tpl": "Hello ${text}", "badge": { "mode": "text", "text": 25 } }, { "type": "divider" }, { "type": "icon", "icon": "cloud", "className": "text-info text-xl", "badge": { "position": "top-left" } }, { "type": "divider" }, { "type": "action", "label": "按钮", "badge": { "mode": "ribbon", "text": "HOT" } }, ] ``` ## 显示文字或数值设置 `mode` 为 `text`，通过 `text` 属性来显示文字或数字，数值为零的时候将不显示。 ```schema: scope="body" [ { "type": "avatar", "badge": { "mode": "text", "text": 10 } }, { "type": "avatar", "className": "m-l", "badge": { "mode": "text", "text": 0 } }, { "type": "avatar", "className": "m-l", "badge": { "mode": "text", "text": "new" } } ] ``` ## 显示位置通过 `position` 来控制角标显示位置，默认 `top-right`，还可以设置为 `top-left`、`bottom-left`、`bottom-right`。 ```schema: scope="body" [ { "type": "avatar", "badge": { "position": "top-left" } }, { "type": "avatar", "className": "m-l", "badge": { "position": "bottom-left" } }, { "type": "avatar", "className": "m-l", "badge": { "position": "bottom-right" } } ] ``` 通过 `offset` 来控制角标显示位置，offset 相对于 position 位置进行水平、垂直偏移。offset 在 mode=ribbon 下设置无效。 ```schema: scope="body" [ { "type": "avatar", "badge": { "offset": [10, 10] } } ] ``` ## 动态数字 `text` 可以取上下文变量。 ```schema { "data": { "myData": 10 }, "type": "page", "body": [ { "type": "avatar", "badge": { "mode": "text", "visibleOn": "this.myData > 1", "text": "${myData}" } } ] } ``` ## 设置封顶值通过 `overflowCount` 可以设置封顶值。超过 overflowCount 的会显示为 ${overflowCount}+，默认的 overflowCount 为 99 ```schema { "type": "page", "body": [ { "type": "avatar", "badge": { "mode": "text", "text": 10, "overflowCount": 9 } } ] } ``` ## 动态控制是否显示角标角标可以直接写表达式来判断是否显示 ```schema { "data": { "myData": 10 }, "type": "page", "body": [ { "type": "avatar", "badge": "this.myData > 1" }, { "type": "avatar", "className": "m-l", "badge": "this.myData > 10" } ] } ``` 还可以通过 `visibleOn` 表达式来动态控制，这样还能设置其他属性 ```schema { "data": { "myData": 10 }, "type": "page", "body": [ { "type": "avatar", "badge": { "visibleOn": "this.myData > 1" } }, { "type": "avatar", "className": "m-l", "badge": { "visibleOn": "this.myData > 10" } } ] } ``` ## 设置大小通过 `size` 来控制大小 ```schema: scope="body" [ { "type": "avatar", "badge": { "mode": "text", "text": 10, "size": 20 } }, { "type": "avatar", "className": "m-l", "badge": { "mode": "text", "text": 10, "size": 12 } }, { "type": "avatar", "className": "m-l", "badge": { "size": 12 } }, { "type": "avatar", "className": "m-l", "badge": { "size": 4 } } ] ``` ## 设置角标级别通过 `level` 来设置角标级别，改变角标背景颜色 ```schema: scope="body" [ { "type": "avatar", "badge": { "mode": "text", "text": 10, "size": 20, "level": "success" } }, ] ``` ## 是否显示动画在默认点状态下，可以通过设置 `animation` 属性来控制是否显示动画 ```schema: scope="body" [ { "type": "avatar", "badge": { "animation": true } } ] ``` ## 自定义样式通过 `style` 来控制展现样式，比如背景及文字的颜色 ```schema: scope="body" [ { "type": "avatar", "badge": { "mode": "text", "text": 10, "style": { "background": "#46C93A" } } }, { "type": "avatar", "className": "m-l", "badge": { "mode": "text", "text": 10, "style": { "background": "#1A5CFF" } } } ] ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------- | ------------------------------------------- | --------- | ---------------------------------------------------------------------- | | mode | `string` | dot | 角标类型，可以是 dot/text/ribbon | | text | `string`\|`number` | | 角标文案，支持字符串和数字，在 mode='dot'下设置无效 | | size | `number` | | 角标大小 | | level | `string` | | 角标级别, 可以是 info/success/warning/danger, 设置之后角标背景颜色不同 | | overflowCount | `number` | 99 | 设置封顶的数字值 | | position | `string` | top-right | 角标位置，可以是 top-right/top-left/bottom-right/bottom-left | | offset | `number[top, left]` | [0, 0] | 角标位置，offset 相对于 position 位置进行水平、垂直偏移 | | className | `string` | | 外层 dom 的类名 | | animation | `boolean` | | 角标是否显示动画 | | style | `object` | | 角标的自定义样式 | | visibleOn | [表达式](../../../docs/concepts/expression) | | 控制角标的显示隐藏 | --- ### Zh CN Components Barcode (`docs/zh-CN/components/barcode.md`) --- title: BarCode 条形码 description: type: 0 group: ⚙ 组件 menuName: BarCode 条形码 icon: order: 62 --- ## 基本用法 ```schema: scope="body" { "type": "barcode", "value": "amis" } ``` ## 条形码配置通过 options 属性配置，具体请参考[这里](https://github.com/lindell/JsBarcode/wiki/Options)，比如 ```schema: scope="body" { "type": "barcode", "value": "123", "options": { "format": "pharmacode", "lineColor": "#0aa", "width": "4", "height": "40", } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------- | -------- | ------ | ------------------------------ | | className | `string` | | 外层 CSS 类名 | | value | `string` | | 显示的颜色值 | | name | `string` | | 在其他组件中，时，用作变量映射 | --- ### Zh CN Components Breadcrumb (`docs/zh-CN/components/breadcrumb.md`) --- title: Breadcrumb 面包屑 description: type: 0 group: ⚙ 组件 menuName: Breadcrumb icon: order: 30 --- ## 基本用法 ```schema: scope="body" { "type": "breadcrumb", "items": [ { "label": "首页", "href": "https://baidu.gitee.com/", "icon": "fa fa-home" }, { "label": "上级页面" }, { "label": "当前页面" } ] } ``` ## 动态数据可以配置 source 来获取上下文中的动态数据，结合 [service](service) 来实现动态生成。 ```schema { "type": "page", "data": { "breadcrumb": [ { "label": "首页", "href": "https://baidu.gitee.com/" }, { "label": "上级页面" }, { "label": "当前页面" } ] }, "body": { "type": "breadcrumb", "source": "${breadcrumb}" } } ``` ## 分隔符 ```schema: scope="body" { "type": "breadcrumb", "separator": ">", "separatorClassName": "text-black", "items": [ { "href": "https://baidu.gitee.com/", "icon": "fa fa-home" }, { "label": "上级页面" }, { "label": "当前页面" } ] } ``` ## 下拉菜单 ```schema: scope="body" { "type": "breadcrumb", "separator": ">", "separatorClassName": "text-black", "items": [ { "label": "首页", "href": "https://baidu.gitee.com/", "icon": "fa fa-home" }, { "label": "上级页面", "dropdown": [ { "label": "选项一", "href": "https://baidu.gitee.com/", }, { "label": "选项二" } ] }, { "label": "当前页面" } ] } ``` ## 最大展示长度 ```schema: scope="body" { "type": "breadcrumb", "separator": ">", "separatorClassName": "text-black", "labelMaxLength": 16, "tooltipPosition": "top", "items": [ { "href": "https://baidu.gitee.com/", "icon": "fa fa-home" }, { "label": "上级页面上级页面上级页面上级页面上级页面" }, { "label": "当前页面" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------------ | -------------------------------- | ------------- | ---------------------------------------------------- | | className | `string` | | 外层类名 | | itemClassName | `string` | | 导航项类名 | | separatorClassName | `string` | | 分割符类名 | | dropdownClassName | `string` | | 下拉菜单类名 | | dropdownItemClassName | `string` | | 下拉菜单项类名 | | separator | `string` | | 分隔符 | | labelMaxLength | `number` | 16 | 最大展示长度 | | tooltipPosition | `top \| bottom \| left \| right` | `top` | 浮窗提示位置 | | source | `string` | | 动态数据 | | items[].label | `string` | | 文本 | | items[].href | `string` | | 链接 | | items[].icon | `string` | | [图标](icon) | | items[].dropdown | `dropdown[]` | | 下拉菜单，dropdown[]的每个对象都包含label、href、icon属性 | --- ### Zh CN Components Button Group (`docs/zh-CN/components/button-group.md`) --- title: ButtonGroup 按钮组 description: type: 0 group: ⚙ 组件 menuName: ButtonGroup icon: order: 30 --- ## 基本用法 ```schema: scope="body" { "type": "button-group", "buttons": [ { "type": "button", "label": "Button", "actionType": "dialog", "dialog": { "confirmMode": false, "title": "提示", "body": "对，你刚点击了！" } }, { "type": "button", "actionType": "url", "url": "https://www.baidu.com", "blank": true, "label": "百度一下" }, { "type": "button", "label": "普通按钮" } ] } ``` ## 垂直模式配置`"vertical": true`，实现垂直模式 ```schema: scope="body" [ { "type": "button-group", "vertical": true, "buttons": [ { "type": "button", "label": "按钮1" }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } ] ``` ## 平铺模式配置 `"tiled": true` 实现平铺模式 ```schema: scope="body" [ { "type": "button-group", "tiled": true, "buttons": [ { "type": "button", "label": "按钮1" }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } ] ``` ## 按钮主题样式配置 `btnLevel` 统一设置按钮主题样式，注意 `buttons ` 或 `options` 中的`level`属性优先级高于`btnLevel`。配置 `btnActiveLevel` 为按钮设置激活态时的主题样式。 ```schema: scope="body" [ { "type": "button-group", "btnLevel": "light", "btnActiveLevel": "warning", "buttons": [ { "type": "button", "label": "按钮1" }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3", "level": "primary" } ] } ] ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | -------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------- | | type | `string` | `"button-group"` | 指定为 button-group 渲染器 | | vertical | `boolean` | `false` | 是否使用垂直模式 | | tiled | `boolean` | `false` | 是否使用平铺模式 | | btnLevel | `'link' \| 'primary' \| 'secondary' \| 'info'\|'success' \| 'warning' \| 'danger' \| 'light'\| 'dark' \| 'default'` | `"default"` | 按钮样式 | | btnActiveLevel | `'link' \| 'primary' \| 'secondary' \| 'info'\|'success' \| 'warning' \| 'danger' \| 'light'\| 'dark' \| 'default'` | `"default"` | 选中按钮样式 | | buttons | `Array` | | [按钮](./action) | | className | `string` | | 外层 Dom 的类名 | --- ### Zh CN Components Button (`docs/zh-CN/components/button.md`) --- title: Button 按钮 description: type: 0 group: ⚙ 组件 menuName: Button 按钮 icon: order: 29 --- ## 基本用法 ```schema: scope="body" { "label": "弹个框", "type": "button", "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } ``` `button` 实际上是 `action` 的别名，更多用法见 [action](./action) ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- | | className | `string` | | 指定添加 button 类名 | | url | `string` | | 点击跳转的地址，指定此属性 button 的行为和 a 链接一致 | | size | `'xs' \| 'sm' \| 'md' \| 'lg' ` | | 设置按钮大小 | | actionType | `'button' \| 'reset' \| 'submit'\| 'clear'\| 'url'` | button | 设置按钮类型 | | level | `'link' \| 'primary' \| 'enhance' \| 'secondary' \| 'info'\|'success' \| 'warning' \| 'danger' \| 'light'\| 'dark' \| 'default'` | default | 设置按钮样式 | | tooltip | `'string' \| 'TooltipObject'` | | 气泡提示内容 | | tooltipPlacement | `'top' \| 'right' \| 'bottom' \| 'left' ` | top | 气泡框位置器 | | tooltipTrigger | `'hover' \| 'focus'` | | 触发 tooltip | | disabled | `'boolean'` | false | 按钮失效状态 | | disabledTip | `'string' \| 'TooltipObject'` | | 按钮失效状态下的提示 | | block | `'boolean'` | false | 将按钮宽度调整为其父宽度的选项 | | loading | `'boolean'` | false | 显示按钮 loading 效果 | | loadingOn | `'string'` | | 显示按钮 loading 表达式 | --- ### Zh CN Components Calendar (`docs/zh-CN/components/calendar.md`) --- title: Calendar 日历日程 description: type: 0 group: ⚙ 组件 menuName: Calendar 日历日程 icon: order: 36 --- ## 基本用法设置 `schedules` 属性 ```schema: scope="body" { "type": "calendar", "value": "1638288000", "schedules": [ { "startTime": "2021-12-11 05:14:00", "endTime": "2021-12-11 06:14:00", "content": "这是一个日程1" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程2" } ] } ``` ## 自定义颜色 ```schema: scope="body" { "type": "calendar", "value": "1638288000", "schedules": [ { "startTime": "2021-12-11 05:14:00", "endTime": "2021-12-11 06:14:00", "content": "这是一个日程1", "className": "bg-success" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程2", "className": "bg-info" } ] } ``` ## 自定义日程展示 ```schema: scope="body" { "type": "calendar", "value": "1638288000", "schedules": [ { "startTime": "2021-12-11 05:14:00", "endTime": "2021-12-11 06:14:00", "content": "这是一个日程1" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程2" } ], "scheduleAction": { "actionType": "drawer", "drawer": { "title": "日程", "body": { "type": "table", "columns": [ { "name": "time", "label": "时间" }, { "name": "content", "label": "内容" } ], "data": "${scheduleData}" } } } } ``` ## 支持从数据源中获取日程 ```schema { "type": "page", "data": { "schedules": [ { "startTime": "2021-12-11 05:14:00", "endTime": "2021-12-11 06:14:00", "content": "这是一个日程1" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程2" } ] }, "body": [ { "type": "calendar", "value": "1638288000", "schedules": "${schedules}" } ] } ``` ## 放大模式 ```schema: scope="body" { "type": "calendar", "value": "1638288000", "largeMode": true, "schedules": [ { "startTime": "2021-12-10 23:59:59", "endTime": "2021-12-11 00:00:00", "content": "这是一个日程1" }, { "startTime": "2021-12-12 00:00:00", "endTime": "2021-12-13 00:00:01", "content": "这是一个日程2" }, { "startTime": "2021-12-20 05:14:00", "endTime": "2021-12-21 05:14:00", "content": "这是一个日程3" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程4" }, { "startTime": "2021-12-22 02:14:00", "endTime": "2021-12-23 05:14:00", "content": "这是一个日程5" }, { "startTime": "2021-12-22 02:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程6" }, { "startTime": "2021-12-22 02:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程7" }, { "startTime": "2021-12-25 12:00:00", "endTime": "2021-12-25 15:00:00", "content": "这是一个日程8" } ] } ``` ## 今日高亮样式自定义 > 2.1.1 及以上版本 ```schema: scope="body" { "type": "calendar", "value": "NOW()", "todayActiveStyle": { "backgroundColor": "#ef4444 !important", "color": "#f8f9fa", "border": "none", "borderRadius": "15px" }, "schedules": [ { "startTime": "2021-12-11 05:14:00", "endTime": "2021-12-11 06:14:00", "content": "这是一个日程1" }, { "startTime": "2021-12-21 05:14:00", "endTime": "2021-12-22 05:14:00", "content": "这是一个日程2" } ] } ``` ## Calendar 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | `string` | `"calendar"` | 指定为 calendar 渲染器 | | schedules | `Array<{startTime: string, endTime: string, content: any, className?: string}> \| string` | | 日历中展示日程，可设置静态数据或从上下文中取数据，startTime 和 endTime 格式参考[文档](https://momentjs.com/docs/#/parsing/string/)，className 参考[背景色](https://baidu.gitee.io/amis/zh-CN/style/background/background-color) | | scheduleClassNames | `Array` | `['bg-warning', 'bg-danger', 'bg-success', 'bg-info', 'bg-secondary']` | 日历中展示日程的颜色，参考[背景色](https://baidu.gitee.io/amis/zh-CN/style/background/background-color) | | scheduleAction | `SchemaNode` | | 自定义日程展示 | | largeMode | `boolean` | `false` | 放大模式 | | todayActiveStyle | `Record` | | 今日激活时的自定义样式 | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`来获取事件产生的数据（`< 2.3.2 及以下版本为 ${event.data.[事件参数名]}`），详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ---------- | ------------------------ | ------------------ | | change | `value: string` 组件的值 | 时间值变化时触发 | | click | `value: string` 组件的值 | 点击日期时触发 | | mouseenter | `value: string` 组件的值 | 鼠标移入日期时触发 | | mouseleave | `value: string` 组件的值 | 鼠标移出日期时触发 | ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | -------- | ------------------------ | ------------------------------------------------ | | clear | - | 清空 | | reset | - | 将值重置为初始值。6.3.0 及以下版本为`resetValue` | | setValue | `value: string` 更新的值 | 更新数据 | --- ### Zh CN Components Card (`docs/zh-CN/components/card.md`) --- title: Card 卡片 description: type: 0 group: ⚙ 组件 menuName: Card 卡片 icon: order: 31 --- ## 基本用法 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 打开链接 > 1.4.0 及以上版本通过 `href` 属性可以设置点击卡片打开外部链接 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 设置头像文本如果没有 avatar，还可以通过 `avatarText` 设置头像文本 ```schema: scope="body" { "type": "card", "href": "https://github.com/baidu/amis", "header": { "title": "标题", "subTitle": "副标题", "description": "这是一段描述", "avatarText": "AMIS" }, "body": "这里是内容" } ``` > 1.5.0 及以上版本可以设置文本背景色，它会根据数据分配一个颜色，主要配合 `cards` 使用 ```schema { "type": "page", "data": { "items": [ { "engine": "Trident", "browser": "Internet Explorer 4.0" }, { "engine": "Chrome", "browser": "Chrome 44" }, { "engine": "Gecko", "browser": "Firefox 1.0" }, { "engine": "Presto", "browser": "Opera 10" }, { "engine": "Webkie", "browser": "Safari 12" } ] }, "body": { "type": "cards", "source": "$items", "card": { "header": { "avatarText": "${engine|substring:0:2|upperCase}", "avatarTextBackground": ["#FFB900", "#D83B01", "#B50E0E", "#E81123", "#B4009E", "#5C2D91", "#0078D7", "#00B4FF", "#008272"] }, "body": [ { "label": "Browser", "name": "browser" } ] } } } ``` ## 点击卡片的行为 > 1.4.0 及以上版本通过设置 `itemAction` 可以设置整个卡片的点击行为 ```schema: scope="body" { "type": "card", "itemAction": { "type": "button", "actionType": "dialog", "dialog": { "title": "详情", "body": "当前描述" } }, "header": { "title": "标题", "subTitle": "副标题", "description": "这是一段描述", "avatarClassName": "pull-left thumb-md avatar b-3x m-r", "avatar": "data:image/svg+xml,%3C%3Fxml version='1.0' standalone='no'%3F%3E%3C!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'%3E%3Csvg t='1631083237695' class='icon' viewBox='0 0 1024 1024' version='1.1' xmlns='http://www.w3.org/2000/svg' p-id='2420' xmlns:xlink='http://www.w3.org/1999/xlink' width='1024' height='1024'%3E%3Cdefs%3E%3Cstyle type='text/css'%3E%3C/style%3E%3C/defs%3E%3Cpath d='M959.872 128c0.032 0.032 0.096 0.064 0.128 0.128v767.776c-0.032 0.032-0.064 0.096-0.128 0.128H64.096c-0.032-0.032-0.096-0.064-0.128-0.128V128.128c0.032-0.032 0.064-0.096 0.128-0.128h895.776zM960 64H64C28.8 64 0 92.8 0 128v768c0 35.2 28.8 64 64 64h896c35.2 0 64-28.8 64-64V128c0-35.2-28.8-64-64-64z' p-id='2421' fill='%23bfbfbf'%3E%3C/path%3E%3Cpath d='M832 288c0 53.024-42.976 96-96 96s-96-42.976-96-96 42.976-96 96-96 96 42.976 96 96zM896 832H128V704l224-384 256 320h64l224-192z' p-id='2422' fill='%23bfbfbf'%3E%3C/path%3E%3C/svg%3E" }, "body": "这里是内容" } ``` 注意它和前面的 `href` 配置冲突，如果设置了 `href` 这个将不会生效 ## 设置多媒体卡片 > 1.5.0 及以上版本通过设置 `media` 可以设置为多媒体卡片, 通过 `mediaPosition` 可以设置多媒体位置 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 设置标签卡片 > 1.5.0 及以上版本 ```schema: scope="body" { "type": "card", "header": { "title": "标题" }, "body": "这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容这里是内容", "secondary": "次要说明", "actions": [ { "type": "button", "label": "操作", "actionType": "dialog", "className": "mr-4", "dialog": { "title": "操作", "body": "你正在编辑该卡片" } }, { "type": "button", "label": "操作", "actionType": "dialog", "className": "mr-2.5", "dialog": { "title": "操作", "body": "你正在编辑该卡片" } }, { "type": "dropdown-button", "level": "link", "icon": "fa fa-ellipsis-h", "className": "pr-1 flex", "hideCaret": true, "buttons": [ { "type": "button", "label": "编辑", "actionType": "dialog", "dialog": { "title": "编辑", "body": "你正在编辑该卡片" } }, { "type": "button", "label": "删除", "actionType": "dialog", "dialog": { "title": "提示", "body": "你删掉了该卡片" } } ] } ], "toolbar": [ { "type": "tpl", "tpl": "标签", "className": "label label-warning" } ] } ``` ## 设置按钮卡片 > 1.5.0 及以上版本按钮卡片一般以卡片形式展示当前卡片的执行语义，例如：创建卡片、添加卡片等场景。 ```schema: scope="body" { "type": "card", "className": "hover:shadow", "body": { "type": "wrapper", "className": "h-32 flex items-center justify-center", "body": [ { "type": "wrapper", "size": "none", "className": "text-center", "body": { "type": "icon", "icon": "plus", "className": "text-2xl", } }, { "type": "wrapper", "size": "none", "body": "点击会有弹框" } ] }, "itemAction": { "type": "button", "actionType": "dialog", "dialog": { "title": "详情", "body": "当前描述" } } } ``` ## 设置文本卡片 > 1.5.0 及以上版本 ```schema: scope="body" { "type": "card", "header": { "className": "items-center", "title": "卡片标题" }, "body": { "type": "wrapper", "size": "none", "body": { "type": "tabs", "tabs": [ { "title": "标签1", "className": "p-0", "tab": [ { "type": "card", "className": "border-0", "header": { "className": "p-0 pb-2", "title": "内容标题" }, "body": "卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容", "bodyClassName": "p-0" }, { "type": "card", "className": "border-0", "header": { "className": "p-0 pb-2", "title": "内容标题" }, "body": "卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容", "bodyClassName": "p-0" } ] }, { "title": "标签2", "className": "p-0", "tab": "卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容卡片内容" } ] } }, "toolbar": [ { "type": "button", "label": "操作", "actionType": "dialog", "dialog": { "title": "操作", "body": "你正在编辑该卡片" } } ] } ``` ## 设置单元格卡片 > 1.5.0 及以上版本 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 配置工具栏 > 1.5.0 及以上版本 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ----------------------------- | ------------------------------------ | ----------------------------------- | ------------------------------------------------- | | type | `string` | `"card"` | 指定为 Card 渲染器 | | className | `string` | | 外层 Dom 的类名 | | href | [模板](../../docs/concepts/template) | | 外部链接 | | header | `Object` | | Card 头部内容设置 | | header.className | `string` | | 头部类名 | | header.title | [模板](../../docs/concepts/template) | | 标题 | | header.titleClassName | `string` | | 标题类名 | | header.subTitle | [模板](../../docs/concepts/template) | | 副标题 | | header.subTitleClassName | `string` | | 副标题类名 | | header.subTitlePlaceholder | `string` | | 副标题占位 | | header.description | [模板](../../docs/concepts/template) | | 描述 | | header.descriptionClassName | `string` | | 描述类名 | | header.descriptionPlaceholder | `string` | | 描述占位 | | header.avatar | [模板](../../docs/concepts/template) | | 图片 | | header.avatarClassName | `string` | `"pull-left thumb avatar b-3x m-r"` | 图片包括层类名 | | header.imageClassName | `string` | | 图片类名 | | header.avatarText | [模板](../../docs/concepts/template) | | 如果不配置图片，则会在图片处显示该文本 | | header.avatarTextBackground | `Array` | | 设置文本背景色，它会根据数据分配一个颜色 | | header.avatarTextClassName | `string` | | 图片文本类名 | | header.highlight | `boolean` | `false` | 是否显示激活样式 | | header.highlightClassName | `string` | | 激活样式类名 | | header.href | [模板](../../docs/concepts/template) | | 点击卡片跳转的链接地址 | | header.blank | `boolean` | `true` | 是否新窗口打开 | | body | `Array` | | 内容容器，主要用来放置非表单项组件 | | bodyClassName | `string` | | 内容区域类名 | | actions | Array<[Action](./action)> | | 配置按钮集合 | | actionsCount | `number` | `4` | 按钮集合每行个数 | | itemAction | [Action](./action) | | 点击卡片的行为 | | media | `Object` | | Card 多媒体部内容设置 | | media.type | `'image'\|'video'` | | 多媒体类型 | | media.url | `string` | | 图片/视频链接 | | media.position | `'left'\|'right'\|'top'\|'bottom'` | `'left'` | 多媒体位置 | | media.className | `string` | `"w-44 h-28"` | 多媒体类名 | | media.isLive | `boolean` | `false` | 视频是否为直播 | | media.autoPlay | `boolean` | `false` | 视频是否自动播放 | | media.poster | `string` | `false` | 视频封面 | | secondary | [模板](../../docs/concepts/template) | | 次要说明 | | toolbar | Array<[Action](./action)> | | 工具栏按钮 | | dragging | `boolean` | `false` | 是否显示拖拽图标 | | selectable | `boolean` | `false` | 卡片是否可选 | | checkable | `boolean` | `true` | 卡片选择按钮是否禁用 | | selected | `boolean` | `false` | 卡片选择按钮是否选中 | | hideCheckToggler | `boolean` | `false` | 卡片选择按钮是否隐藏 | | multiple | `boolean` | `false` | 卡片是否为多选 | | useCardLabel | `boolean` | `true` | 卡片内容区的表单项 label 是否使用 Card 内部的样式 | --- ### Zh CN Components Cards (`docs/zh-CN/components/cards.md`) --- title: Cards 卡片组 description: type: 0 group: ⚙ 组件 menuName: Cards 卡片组 icon: order: 32 --- 卡片展示，不支持配置初始化接口初始化数据域，所以需要搭配类似像`Service`这样的，具有配置接口初始化数据域功能的组件，或者手动进行数据域初始化，然后通过`source`属性，获取数据链中的数据，完成数据展示。 ## 基本用法这里我们使用手动初始数据域的方式，即配置`data`属性，进行数据域的初始化。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 或者你也可以使用 CRUD 的 [card 模式](./crud#cards-%E5%8D%A1%E7%89%87%E6%A8%A1%E5%BC%8F) ## 当 cards 在 crud 中且配置了批量操作按钮时可点选如果配置了 `checkOnItemClick`，当用户点击卡片时就能选中这个卡片，而不是只能点击勾选框才能选中 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 瀑布流布局设置 `"masonryLayout": true` 开启瀑布流布局模式，适合展示不同高度的卡片内容，比如图片列表、社交媒体流等场景。 > 瀑布流布局支持两种方式设置列数: > > 1. 通过 `columnsCount` 设置固定列数 > 2. 通过 `itemClassName` 设置响应式列数,如 `Grid-col--xs6 Grid-col--sm4 Grid-col--md3` 可以在不同屏幕尺寸下展现不同的列数 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------------- | -------------------------------------------- | ------------------- | ------------------------------ | | type | `string` | | `"cards"` 指定为卡片组。 | | title | [模板](../../docs/concepts/template) | | 标题 | | source | [数据映射](../../docs/concepts/data-mapping) | `${items}` | 数据源, 获取当前数据域中的变量 | | placeholder | [模板](../../docs/concepts/template) | '暂无数据' | 当没数据的时候的文字提示 | | className | `string` | | 外层 CSS 类名 | | headerClassName | `string` | `amis-grid-header` | 顶部外层 CSS 类名 | | footerClassName | `string` | `amis-grid-footer` | 底部外层 CSS 类名 | | itemClassName | `string` | `col-sm-4 col-md-3` | 卡片 CSS 类名 | | card | [Card](./card) | | 配置卡片信息 | | selectable | `boolean` | `false` | 卡片组是否可选 | | multiple | `boolean` | `true` | 卡片组是否为多选 | | checkOnItemClick | `boolean` | | 点选卡片内容是否选中卡片 | ## 动作表 > 6.4.0 或更高版本当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | select | `args.index` 可选，指定行数，支持表达式
`args.condition` 可选，通过表达式指定更新哪些行，支持条件组合 index` | 设置列表的选中项 | | selectAll | - | 设置列表全部项选中 | | clearAll | - | 清空列表所有选中项 | | initDrag | - | 开启列表拖拽排序功能 | | cancelDrag | - | 放弃列表拖拽排序功能 | | setValue | `args.value`: object
`args.index` 可选，指定行数，支持表达式
`args.condition` 可选，通过表达式指定更新哪些行，支持条件组合 | 更新列表记录 | | submitQuickEdit | | 快速编辑数据提交 | ### select - `args.index` 可选，指定行数，支持表达式 - `args.condition` 可选，通过表达式指定更新哪些行，支持条件组合 ```schema: scope="body" [ { "type": "button-toolbar", "className": "m-b", "buttons": [ { "name": "trigger1", "id": "trigger1", "type": "action", "label": "选中前两个", "onEvent": { "click": { "actions": [ { "actionType": "select", "componentId": "cards-select", "args": { "index": "0,1" } } ] } } } ] }, { "type": "service", "api": "/api/mock2/sample?perPage=5", "body": [ { "id": "cards-select", "type": "cards", "source": "$rows", "selectable": true, "multiple": true, "card": { "body": [ { "label": "Engine", "name": "engine" }, { "label": "Browser", "name": "browser" }, { "name": "version", "label": "Version" } ] } } ] } ] ``` ### selectAll ```schema: scope="body" [ { "type": "button-toolbar", "className": "m-b", "buttons": [ { "name": "trigger2", "id": "trigger2", "type": "action", "label": "设置列表全部项选中", "onEvent": { "click": { "actions": [ { "actionType": "selectAll", "componentId": "cards-select", "description": "点击设置指定列表全部内容选中" } ] } } } ] }, { "type": "service", "api": "/api/mock2/sample?perPage=10", "body": [ { "id": "cards-select", "type": "cards", "source": "$rows", "selectable": true, "multiple": true, "card": { "body": [ { "label": "Engine", "name": "engine" }, { "label": "Browser", "name": "browser" }, { "name": "version", "label": "Version" } ] } } ] } ] ``` ### clearAll ```schema: scope="body" [ { "type": "button-toolbar", "className": "m-b", "buttons": [ { "name": "trigger3", "id": "trigger3", "type": "action", "label": "清空列表全部选中项", "onEvent": { "click": { "actions": [ { "actionType": "clearAll", "componentId": "cards-select", "description": "点击设置指定列表全部选中项清空" } ] } } } ] }, { "type": "service", "api": "/api/mock2/sample?perPage=10", "body": [ { "id": "cards-select", "type": "cards", "source": "$rows", "selectable": true, "multiple": true, "card": { "body": [ { "label": "Engine", "name": "engine" }, { "label": "Browser", "name": "browser" }, { "name": "version", "label": "Version" } ] } } ] } ] ``` ### initDrag & cancelDrag ```schema: scope="body" [ { "type": "button-toolbar", "className": "m-b", "buttons": [ { "name": "trigger4", "id": "trigger4", "type": "action", "label": "开启列表行排序", "onEvent": { "click": { "actions": [ { "actionType": "initDrag", "componentId": "cards-select", "description": "点击开启列表行排序功能" } ] } } }, { "name": "trigger5", "id": "trigger5", "type": "action", "label": "取消列表行排序", "onEvent": { "click": { "actions": [ { "actionType": "cancelDrag", "componentId": "cards-select", "description": "点击取消列表行排序功能" } ] } } } ] }, { "type": "service", "api": "/api/mock2/sample?perPage=10", "body": [ { "id": "cards-select", "type": "cards", "source": "$rows", "card": { "body": [ { "label": "Engine", "name": "engine" }, { "label": "Browser", "name": "browser" }, { "name": "version", "label": "Version" } ] } } ] } ] ``` ### setValue #### 更新列表记录 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 更新指定行记录可以通过指定`index`或者`condition`来分别更新指定索引的行记录和指定满足条件（条件表达式或者 ConditionBuilder）的行记录，另外`replace`同样生效，即可以完全替换指定行记录，也可以对指定行记录做合并。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Zh CN Components Carousel (`docs/zh-CN/components/carousel.md`) --- title: Carousel 轮播图 description: type: 0 group: ⚙ 组件 menuName: Carousel 幻灯片 icon: order: 33 --- ## 基本用法 ```schema: scope="body" { "type": "carousel", "auto": false, "thumbMode": "cover", "animation": "slide", "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }, { "html": "

carousel data

" }, { "thumbMode": "contain", "image": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ] } ``` ## 动态列表轮播图组件目前没有获取数据的配置，因此需要依赖 `service` 来获取数据。 ```schema: scope="body" { "type": "page", "body": { "type": "service", "api": "/api/mock2/options/carousel", "body": { "type": "carousel", "name": "imageList" } } } ``` 目前数据关联是通过 name 的方式，因此 api 返回应该是类似这样的： ``` { status: 0, msg: '', data: { imageList: [{ "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }] } } ``` 其中的 `imageList` 要和配置的 `name` 值对应。 ## 点击图片打开外部链接 > 1.3.3 及以上版本需要放回的字段中除了前面的 image，还有 href 属性 ```schema: scope="body" { "type": "page", "data": { "imageList": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png", "href": "https://github.com/baidu/amis" } ] }, "body": { "type": "carousel", "name": "imageList" } } ``` ## 自定义轮播图的展现通过配置 `itemSchema` 可以自定义轮播图的展现，比如图片默认背景配置是 contain，可以改成 cover： ``` itemSchema: { type: 'tpl', tpl: '

' } ``` ## 多图展示 > `2.8.1` 及以上版本 ```schema: scope="body" { "type": "carousel", "auto": false, "thumbMode": "cover", "animation": "slide", "multiple": {count: 3}, "interval": 1000, "duration": 5000, "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692722/4f3cb4202335.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395692942/d8e4992057f9.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693148/1314a2a3d3f6.jpeg@s_0,w_216,l_1,f_jpg,q_80" }, { "image": "https://internal-amis-res.cdn.bcebos.com/images/2020-1/1578395693379/8f2e79f82be0.jpeg@s_0,w_216,l_1,f_jpg,q_80" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | ---------------------------- | ----------------------------------------------------- | ---------------------- | ------------------------------------------------------- | ------- | | type | `string` | `"carousel"` | 指定为 Carousel 渲染器 | | className | `string` | `"panel-default"` | 外层 Dom 的类名 | | options | `array` | `[]` | 轮播面板数据 | | options.image | `string` | | 图片链接 | | options.href | `string` | | 图片打开网址的链接 | | options.imageClassName | `string` | | 图片类名 | | options.title | `string` | | 图片标题 | | options.titleClassName | `string` | | 图片标题类名 | | options.description | `string` | | 图片描述 | | options.descriptionClassName | `string` | | 图片描述类名 | | options.html | `string` | | HTML 自定义，同[Tpl](./tpl)一致 | | itemSchema | `object` | | 自定义`schema`来展示数据 | | auto | `boolean` | `true` | 是否自动轮播 | | interval | `string` | `5s` | 切换动画间隔 | | duration | `number` | `500` | 切换动画时长（ms） | | width | `string` | `auto` | 宽度 | | height | `string` | `200px` | 高度 | | controls | `array` | `['dots', 'arrows']` | 显示左右箭头、底部圆点索引 | | controlsTheme | `string` | `light` | 左右箭头、底部圆点索引颜色，默认`light`，另有`dark`模式 | | animation | `string` | fade | 切换动画效果，默认`fade`，另有`slide`模式，`marquee`跑马灯模式 | | thumbMode | `string` | `"cover" \| "contain"` | 图片默认缩放模式 | | multiple | `object` | `{count: 1}` | 多图展示，count 表示展示的数量 | `2.8.1` | | alwaysShowArrow | `boolean` | `false` | 是否一直显示箭头，为 false 时鼠标 hover 才会显示 | `2.8.1` | | icons | {prev: `SchemaCollection`; next: `SchemaCollection`;} | | 自定义箭头图标 | `2.8.1` | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | -------- | -------------------------------------------------------------------------------- | ---------------- | | change | `activeIndex: number` 激活图片的索引
`prevIndex: number` 上一张图片的索引 | 轮播图切换时触发 | ### change ```schema: scope="body" { "type": "carousel", "auto": false, "thumbMode": "cover", "animation": "slide", "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }, { "html": "

carousel data

" }, { "thumbMode": "contain", "image": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ], "onEvent": { "change": { "actions": [ { "actionType": "toast", "args": { "msg": "滚动至${activeIndex}" } } ] } } } ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | ---------- | ------------------------------------ | ---------- | | next | - | 下一张 | | prev | - | 上一张 | | goto-image | `activeIndex: number` 切换图片的索引 | 切换轮播图 | ### next ```schema: scope="body" [ { "type": "action", "label": "下一张", "className": "mr-3 mb-3", "onEvent": { "click": { "actions": [ { "actionType": "next", "componentId": "carousel_001" } ] } } }, { "type": "carousel", "id": "carousel_001", "auto": false, "thumbMode": "cover", "animation": "slide", "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }, { "html": "

carousel data

" }, { "thumbMode": "contain", "image": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ] } ] ``` ### prev ```schema: scope="body" [ { "type": "action", "label": "上一张", "className": "mr-3 mb-3", "onEvent": { "click": { "actions": [ { "actionType": "prev", "componentId": "carousel_002" } ] } } }, { "type": "carousel", "id": "carousel_002", "auto": false, "thumbMode": "cover", "animation": "slide", "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }, { "html": "

carousel data

" }, { "thumbMode": "contain", "image": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ] } ] ``` ### goto-image ```schema: scope="body" [ { "type": "action", "label": "滚动到第三张", "className": "mr-3 mb-3", "onEvent": { "click": { "actions": [ { "actionType": "goto-image", "componentId": "carousel_003", "args": { "activeIndex": "${index}" } } ] } } }, { "type": "carousel", "id": "carousel_003", "auto": false, "thumbMode": "cover", "animation": "slide", "height": 300, "options": [ { "image": "https://internal-amis-res.cdn.bcebos.com/images/2019-12/1577157239810/da6376bf988c.png" }, { "html": "

carousel data

" }, { "thumbMode": "contain", "image": "https://suda.cdn.bcebos.com/amis/images/alice-macaw.jpg" } ] } ] ``` --- ### Zh CN Components Chart (`docs/zh-CN/components/chart.md`) --- title: Chart 图表 description: type: 0 group: ⚙ 组件 menuName: Chart 图标 icon: order: 34 --- 图表渲染器，采用 echarts 渲染，配置格式跟 echarts 相同，[echarts 配置文档](https://echarts.apache.org/zh/option.html#title) ## 基本用法 ```schema: scope="body" { "type": "chart", "api": "/api/mock2/chart/chart", "interval": 5000 } ``` api 返回支持两种格式，一种是直接返回完整 echarts 配置，数据包含在配置里，具体格式请参考后面的静态数据写法，另一种是返回纯数据，具体请参考动态数据写法。 ## 静态数据在 `config` 里填写完整的 echarts 配置，这里的数据是静态的。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 动态数据如果要实现动态数据，需要在 config 中做调整，比如将前面的例子改成如下写法 ```schema: scope="body" { "type": "chart", "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] }, "yAxis": { "type": "value" }, "series": [{ "data": "${line || []}", "type": "line" }] } } ``` > Echarts 中有些配置不能为未定义，所以要使用变量，最好使用类似上面的 `${line || []}` 写法配置默认值，保证在数据加载完前渲染也不会报错其中 api 返回内容是如下写法，可以看到通过[数据映射](../../docs/concepts/data-mapping)语法，我们可以将 api 放回结果中的 line 字段作为折线的数据。 ```json { "status": 0, "msg": "ok", "data": { "line": [65, 63, 10, 73, 42, 21] } } ``` 除了 `config` 中的 `data`，`config` 里的其它属性也都支持数据映射，还能支持数据映射中的各种过滤器。 ### 使用上层数据接口有时候数据是在上层获取的，比如通过 service 中返回了数据，这时需要通过 `trackExpression` 来指定跟踪什么数据，比如下面的例子，数据是从 service 获取的就需要配置 `trackExpression`。 > 如果`trackExpression` 追踪的数据是**对象数据**，可以使用[数据映射](../../docs/concepts/data-mapping)的`json`方法将数据序列化之后再比较，例如`"trackExpression": "${fieldToTrack|json}"` ```schema: scope="body" { "type": "service", "api": "/api/mock2/chart/chartData", "interval": 3000, "body": [ { "type": "chart", "trackExpression": "${line}", "config": { "xAxis": { "type": "category", "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] }, "yAxis": { "type": "value" }, "series": [{ "data": "${line || []}", "type": "line" }] } } ] } ``` ## 配置图表点击行为可以通过配置`"clickAction": {}`，来指定图表节点的点击行为，支持 amis 的 [行为](./action)。然后在配置的行为中可以通过 [数据链](../../docs/concepts/datascope-and-datachain) 获取到 [echarts 鼠标事件](https://echarts.apache.org/zh/api.html#events.%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6.click) 的值，例如下面例子中可以通过`${value|json}`获取到点击节点的`传入的数据值` > 点击下面坐标中的节点查看效果！ ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 具体能拿到的参数请参考 [Echarts](https://echarts.apache.org/handbook/zh/concepts/event#%E9%BC%A0%E6%A0%87%E4%BA%8B%E4%BB%B6%E7%9A%84%E5%A4%84%E7%90%86) 的文档，官方定义如下 ```typescript type EventParams = { // 当前点击的图形元素所属的组件名称， // 其值如 'series'、'markLine'、'markPoint'、'timeLine' 等。 componentType: string; // 系列类型。值可能为：'line'、'bar'、'pie' 等。当 componentType 为 'series' 时有意义。 seriesType: string; // 系列在传入的 option.series 中的 index。当 componentType 为 'series' 时有意义。 seriesIndex: number; // 系列名称。当 componentType 为 'series' 时有意义。 seriesName: string; // 数据名，类目名 name: string; // 数据在传入的 data 数组中的 index dataIndex: number; // 传入的原始数据项 data: Object; // sankey、graph 等图表同时含有 nodeData 和 edgeData 两种 data， // dataType 的值会是 'node' 或者 'edge'，表示当前点击在 node 还是 edge 上。 // 其他大部分图表中只有一种 data，dataType 无意义。 dataType: string; // 传入的数据值 value: number | Array; // 数据图形的颜色。当 componentType 为 'series' 时有意义。 color: string; }; ``` ## 远程拉取动态配置项配置`api`，来远程拉取图标配置 ```schema: scope="body" { "type": "chart", "api": "/api/mock2/chart/chart1" } ``` ## 通过组件间联动，更新图表 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 对函数配置的特殊支持 ECharts 中有些配置项可以写函数，比如 formatter 和 sort，但在 JSON 里无法写函数，因此我们做了特殊支持，将看起来像函数的字符串转成了函数： ```schema: scope="body" { "type": "chart", "config": { "legend": { "formatter": "function (name) { return 'Legend ' + name;}" }, "dataset": { "source": [["type","2012","2013","2014","2015","2016"],["Forest",320,332,301,334,390],["Steppe",220,182,191,234,290],["Desert",150,232,201,154,190],["Wetland",98,77,101,99,40]] }, "xAxis": { "type": "category", "axisTick": { "show": false } }, "yAxis": {}, "series": [{"type":"bar","seriesLayoutBy":"row"},{"type":"bar","seriesLayoutBy":"row"},{"type":"bar","seriesLayoutBy":"row"},{"type":"bar","seriesLayoutBy":"row"}] } } ``` ## 使用地图从 amis 1.1.0 版本开始，ECharts 版本升级到 5.0.0，为了规避政策风险，在这个版本删除了之前的地图 geojson，如果需要这个功能需要手动引入。方法是去 `https://github.com/apache/echarts/tree/master/test/data/map/js` 下载 `china.js` 和 `world.js`。对于 npm 版本，直接 `import` 这两个文件就行。对于 JS SDK 版本，需要先加入如下代码如下方式： ```javascript window.echarts = amisRequire('echarts'); ``` 然后通过 script 标签引入这两个文件，或者用下面的新版方法 ## 地图配置 > 2.4.1 及以上版本新增了 `mapURL` 及 `mapName` 两个配置项 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 加载百度地图配置 `loadBaiduMap` 后会加载百度地图，需要配置 `ak` ```schema: scope="body" { "type": "chart", "loadBaiduMap": true, "ak": "LiZT5dVbGTsPI91tFGcOlSpe5FDehpf7", "config": { "bmap": { "center": [116.414, 39.915], "zoom": 14, "roam": true } } } ``` ## 动态处理 echart 配置 echarts 的 config 一般是静态配置的，支持简单的数据映射。如果你觉得还不够灵活可以通过自己手写逻辑代码来完成配置。通过配置 dataFiler 来处理。 ```schema: scope="body" { "type": "chart", "data": { "line": [65, 63, 10, 73, 42, 21], "line2": [22, 33, 90, 20, 11, 33] }, "config": { "xAxis": { "type": "category", "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] }, "yAxis": { "type": "value" } }, "dataFilter": "config.series = [];Object.keys(data).forEach(function(key) {config.series.push({data: data[key], type: 'line'})})" } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------------ | -------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | `string` | `"chart"` | 指定为 chart 渲染器 | | className | `string` | | 外层 Dom 的类名 | | body | [SchemaNode](../../docs/types/schemanode) | | 内容容器 | | api | [api](../../docs/types/api) | | 配置项接口地址 | | source | [数据映射](../../docs/concepts/data-mapping) | | 通过数据映射获取数据链中变量值作为配置 | | initFetch | `boolean` | | 组件初始化时，是否请求接口 | | interval | `number` | | 刷新时间(最小 1000) | | config | `object` 或 `string` | | 设置 eschars 的配置项,当为`string`的时候可以设置 function 等配置项 | | style | `object` | | 设置根元素的 style | | width | `string` | | 设置根元素的宽度 | | height | `string` | | 设置根元素的高度 | | replaceChartOption | `boolean` | `false` | 每次更新是完全覆盖配置项还是追加？ | | trackExpression | `string` | | 当这个表达式的值有变化时更新图表 | | dataFilter | `string` | | 自定义 echart config 转换，函数签名：function(config, echarts, data) {return config;} 配置时直接写函数体。其中 config 是当前 echart 配置，echarts 就是 echarts 对象，data 为上下文数据。 | | mapURL | [api](../../docs/types/api) | | 地图 geo json 地址 | | mapName | string | | 地图名称 | | loadBaiduMap | boolean | | 加载百度地图 | ## 事件表 > 2.4.1 及以上版本当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- | | init | - | 组件实例被创建并插入 DOM 中时触发。2.4.1 及以上版本 | | click | 查看[ECharst 事件与行为文档](https://echarts.apache.org/handbook/zh/concepts/event/) | 鼠标点击时触发 | | mouseover | 查看[ECharst 事件与行为文档](https://echarts.apache.org/handbook/zh/concepts/event/) | 鼠标悬浮时触发 | | legendselectchanged | 查看[ECharst 事件与行为文档](https://echarts.apache.org/handbook/zh/concepts/event/) | 切换图例选中状态时触发 | | finished | {echarts: echarts.init(ref, theme)} | echarts 图表绘制完成, version > 6.11.0 | ### init ```schema: scope="body" { "type": "chart", "id": "chart01", "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "yAxis": { "type": "value" }, "series": [ { "data": "${line || []}", "type": "line" } ] }, "onEvent": { "init": { "actions": [ { "actionType": "toast", "args": { "msg": "init" } } ] } } } ``` ### click 用户鼠标操作点击时触发，例如点击下图蓝色线条上的数据点，将弹出详情。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### mouseover 用户鼠标悬浮时触发，例如悬浮到下图蓝色线条上的数据点，将弹出详情。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### legendselectchanged 图例开关的行为会触发 legendselectchanged 事件。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### finished echarts渲染完触发`finished`事件, version>6.11.0。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | -------- | -------------------------- | ------------------------------------------ | | reload | - | 刷新（重新加载） | | setValue | `value: object` 更新的数据 | 更新数据，等于更新图表所依赖数据域中的变量 | 2.4.1 及以上版本，除了以上动作，还支持直接触发[ECharts 组件行为](https://echarts.apache.org/handbook/zh/concepts/event/#%E4%BB%A3%E7%A0%81%E8%A7%A6%E5%8F%91-echarts-%E4%B8%AD%E7%BB%84%E4%BB%B6%E7%9A%84%E8%A1%8C%E4%B8%BA)，即通过`actionType`指定行为名称，行为配置通过`args: {动作配置项名称: xxx}`来配置具体的参数。 ### reload #### 只做刷新重新发送`api`请求，刷新 Chart 时，只配置`componentId`目标组件 ID 即可。 ```schema: scope="body" [ { "type": "button", "label": "刷新请求", "onEvent": { "click": { "actions": [ { "componentId": "chart01", "actionType": "reload" } ] } } }, { "type": "chart", "id": "chart01", "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "yAxis": { "type": "value" }, "series": [ { "data": "${line || []}", "type": "line" } ] } } ] ``` #### 发送数据并刷新刷新 Chart 组件时，如果配置了`data`，将发送`data`给目标组件，并将该数据合并到目标组件的数据域中（如果配置`"dataMergeMode": "override"`将覆盖目标组件的数据），然后重新请求数据。 ```schema: scope="body" [ { "type": "button", "label": "刷新请求", "onEvent": { "click": { "actions": [ { "componentId": "chart01", "actionType": "reload", "data": { "xAxis": [ "周一", "周二", "周三", "周四", "周五", "周六" ] } } ] } } }, { "type": "chart", "id": "chart01", "data": { "xAxis": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": "${xAxis}" }, "yAxis": { "type": "value" }, "series": [ { "data": "${line || []}", "type": "line" } ] } } ] ``` ### setValue 通过`setValue`更新指定图表的数据。 #### 合并数据默认`setValue`会将新数据与目标组件数据进行合并。 ```schema: scope="body" [ { "type": "button", "label": "更新数据", "onEvent": { "click": { "actions": [ { "componentId": "chart02", "actionType": "setValue", "args": { "value": { "line":[98,41,51,2,90,40] } } } ] } } }, { "type": "chart", "id": "chart02", "data": { "xAxis": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": "${xAxis}" }, "yAxis": { "type": "value" }, "series": [ { "data": "${line || []}", "type": "line" } ] } } ] ``` #### 覆盖数据可以通过`"dataMergeMode": "override"`来覆盖目标组件数据。 ```schema: scope="body" [ { "type": "button", "label": "更新数据", "onEvent": { "click": { "actions": [ { "componentId": "chart02", "actionType": "setValue", "args": { "value": { "line":[98,41,51,2,90,40] } }, "dataMergeMode": "override" } ] } } }, { "type": "chart", "id": "chart02", "data": { "xAxis": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ] }, "api": "/api/mock2/chart/chartData", "config": { "xAxis": { "type": "category", "data": "${xAxis}" }, "yAxis": { "type": "value" }, "series": [ { "data": "${line || []}", "type": "line" } ] } } ] ``` ### 其他动作 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Zh CN Components Code (`docs/zh-CN/components/code.md`) --- title: Code 代码高亮 description: type: 0 group: ⚙ 组件 menuName: Code icon: order: 38 --- 使用代码高亮的方式来显示一段代码。 ## 基本用法 ```schema: scope="body" { "type": "code", "language": "html", "value": "

html

" } ``` ## 语言设置默认语言是 html，可以通过 language 指定以下语言： `bat`、 `c`、 `coffeescript`、 `cpp`、 `csharp`、 `css`、 `dockerfile`、 `fsharp`、 `go`、 `handlebars`、 `html`、 `ini`、 `java`、 `javascript`、 `json`、 `less`、 `lua`、 `markdown`、 `msdax`、 `objective-c`、 `php`、 `plaintext`、 `postiats`、 `powershell`、 `pug`、 `python`、 `r`、 `razor`、 `ruby`、 `sb`、 `scss`、`shell`、 `sol`、 `sql`、 `swift`、 `typescript`、 `vb`、 `xml`、 `yaml` ```schema { "body": { "type": "code", "language": "javascript", "value": "(function () {\n let amis = amisRequire('amis/embed');\n let amisJSON = {\n type: 'page',\n title: '表单页面',\n body: {\n type: 'form',\n mode: 'horizontal',\n api: '/saveForm',\n body: [\n {\n label: 'Name',\n type: 'input-text',\n name: 'name'\n },\n {\n label: 'Email',\n type: 'input-email',\n name: 'email'\n }\n ]\n }\n };\n let amisScoped = amis.embed('#root', amisJSON);\n})();" } } ``` language 支持从上下文获取数据 ```schema { "type": "page", "data": { "lang": "javascript" }, "body": { "type": "code", "language": "${lang}", "value": "function amis() {\n console.log('amis');\n}" } } ``` ## 动态数据可以使用 name 来从上下文来获取数据，比如 ```schema { "type": "page", "data": { "sourcecode": "

html

" }, "body": { "type": "code", "language": "html", "name": "sourcecode" } } ``` 因此它还能放在表单、crud 中实现代码的展现。 ## 主题及 tab 大小通过 `editorTheme` 设置主题，`tagSize` 设置 tab 宽度 ```schema: scope="body" { "type": "code", "language": "javascript", "tagSize": 4, "value": "function amis() {\n\tconsole.log('amis');\n}" } ``` ## 超出换行 > 1.5.1 及以上版本通过 `wordWrap` 设置是否折行，默认是折行 ```schema: scope="body" { "type": "code", "language": "typescript", "tagSize": 4, "wordWrap": false, "value": "function amis() {\n\tconsole.log('amis')\tconsole.log('amis')\tconsole.log('amis')\tconsole.log('amis')\tconsole.log('amis')\tconsole.log('amis');\n}" } ``` ## 最大高度通过配置 `maxHeight` 可以实现最大高度，超出滚动 ```schema { "body": { "type": "code", "language": "javascript", "className": "b-a", "maxHeight": 200, "value": "(function () {\n let amis = amisRequire('amis/embed');\n let amisJSON = {\n type: 'page',\n title: '表单页面',\n body: {\n type: 'form',\n mode: 'horizontal',\n api: '/saveForm',\n body: [\n {\n label: 'Name',\n type: 'input-text',\n name: 'name'\n },\n {\n label: 'Email',\n type: 'input-email',\n name: 'email'\n }\n ]\n }\n };\n let amisScoped = amis.embed('#root', amisJSON);\n})();" } } ``` ## 自定义语言高亮还可以通过 `customLang` 参数来自定义高亮，详情参考[示例](../../../examples/code)。 `customLang` 中主要是 `tokens` 设置，这里是语言词法配置，它有 4 个配置项： - `name`：词法名称 - `regex`：词法的正则匹配，注意因为是在字符串中，这里正则中如果遇到 `\` 需要写成 `\\` - `regexFlags`: 可选，正则的标志参数 - `color`：颜色 - `fontStyle`: 可选，字体样式，比如 `bold` 代表加粗 ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ----------- | ------------------ | ------ | ---------------------------------- | | className | `string` | | 外层 CSS 类名 | | value | `string` | | 显示的颜色值 | | name | `string` | | 在其他组件中，时，用作变量映射 | | language | `string` | | 所使用的高亮语言，默认是 plaintext | | tabSize | `number` | 4 | 默认 tab 大小 | | editorTheme | `string` | 'vs' | 主题，还有 'vs-dark' | | wordWrap | `string` | `true` | 是否折行 | | maxHeight | `string`\|`number` | | 最大高度 | --- ### Zh CN Components Collapse (`docs/zh-CN/components/collapse.md`) --- title: Collapse 折叠器 description: type: 0 group: ⚙ 组件 menuName: Collapse 折叠器 icon: order: 36 --- ## 基本用法 ```schema: scope="body" { "type": "collapse-group", "activeKey": ["1"], "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" }, { "type": "collapse", "key": "3", "header": "标题3", "body": "这里是内容3" } ] } ``` ## 手风琴模式 ```schema: scope="body" { "type": "collapse-group", "activeKey": ["1"], "accordion": true, "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" }, { "type": "collapse", "key": "3", "header": "标题3", "body": "这里是内容3" } ] } ``` ## 自定义图标 ```schema: scope="body" { "type": "collapse-group", "activeKey": ["1"], "expandIcon": { "type": "icon", "icon": "caret-right" }, "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" }, { "type": "collapse", "key": "3", "header": "标题3", "body": "这里是内容3" } ] } ``` ## 设置图标位置 ```schema: scope="body" { "type": "collapse-group", "expandIconPosition": "right", "activeKey": ["1"], "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" }, { "type": "collapse", "key": "3", "header": "标题3", "body": "这里是内容3" } ] } ``` ## 面板嵌套 ```schema: scope="body" { "type": "collapse-group", "activeKey": ["1"], "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": { "type": "collapse-group", "activeKey": ["1"], "body": [ { "type": "collapse", "key": "1", "header": "嵌套面板标题", "body": "嵌套面板内容" } ] } }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" } ] } ``` ## 折叠面板禁用 ```schema: scope="body" { "type": "collapse-group", "activeKey": ["1"], "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "disabled": true, "key": "2", "header": "标题2", "body": "这里是内容2" } ] } ``` ## 折叠面板图标隐藏 ```schema: scope="body" { "type": "collapse-group", "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "showArrow": false, "key": "2", "header": "标题2", "body": "这里是内容2" } ] } ``` ## 类FieldSet样式当Collapse组件作为Form组件的子元素时，`enableFieldSetStyle`属性可以控制Collapse组件样式风格，开启后转换为类似[FieldSet组件](./form/fieldset)的样式，默认开启。 ```schema: scope="body" { "type": "form", "body": [ { "type": "switch", "name": "enableFieldSetStyle", "label": "切换展示方式", "mode": "horizontal", "value": true }, { "type": "collapse-group", "activeKey": ["1"], "enableFieldSetStyle": "${enableFieldSetStyle}", "body": [ { "type": "collapse", "key": "1", "header": "标题1", "body": "这里是内容1" }, { "type": "collapse", "key": "2", "header": "标题2", "body": "这里是内容2" }, { "type": "collapse", "key": "3", "header": "标题3", "body": "这里是内容3" } ] } ] } ``` ## CollapseGroup 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | ------------------ | ------------------------------------------------------ | ------------------ | ----------------------------------- | --- | | type | `string` | `"collapse-group"` | 指定为 collapse-group 渲染器 | | activeKey | `Array \| string \| number` | - | 初始化激活面板的 key | | accordion | `boolean` | `false` | 手风琴模式 | | expandIcon | `SchemaNode` | - | 自定义切换图标 | | expandIconPosition | `string` | `"left"` | 设置图标位置，可选值`left \| right` | | enableFieldSetStyle | `boolean` | `true` | 当Collapse作为Form组件的子元素时，开启该属性后组件样式设置为FieldSet组件的样式，默认开启 | `3.5.0` | ## CollapseGroup 事件表当前组件会对外派发以下事件，可以通过 onEvent 来监听这些事件，并通过 actions 来配置执行的动作，在 actions 中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据，详细查看事件动作。 | 事件名称 | 事件参数 | 说明 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | change | `activeKeys: Array` 当前展开的索引列表
`collapseId: string \| number` 折叠器索引
`collapsed: boolean` 折叠器状态 | 折叠面板折叠状态改变时触发 | ### change 折叠面板折叠状态改变时触发。 ```schema: scope="body" { "type": "collapse-group", "activeKey": [ "1" ], "body": [ { "type": "collapse", "key": "1", "active": true, "header": "标题1", "body": [ { "type": "tpl", "tpl": "这里是内容1", "wrapperComponent": "", "inline": false, "id": "u:757ad799da08" } ], "id": "u:b1b68dfbb08d" }, { "type": "collapse", "key": "2", "header": "标题2", "body": [ { "type": "tpl", "tpl": "这里是内容1", "wrapperComponent": "", "inline": false, "id": "u:92caa03f227e" } ], "id": "u:621a22c8b18c" } ], "id": "u:23e4c5ec9c89", "onEvent": { "change": { "weight": 0, "actions": [ { "actionType": "toast", "args": { "msgType": "info", "position": "top-right", "closeButton": true, "showIcon": true, "title": "折叠状态改变", "msg": "activeKeys: ${event.data.activeKeys | json}, collapseId: ${event.data.collapseId}, collapsed: ${event.data.collapsed}", "className": "theme-toast-action-scope" } } ] } } } ``` ## Collapse 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | --------- | ---------------------- | ------------ | ---------------------- | --- | | type | `string` | `"collapse"` | 指定为 collapse 渲染器 | | disabled | `boolean` | `false` | 禁用 | | collapsed | `boolean` | `true` | 初始状态是否折叠 | | key | `string \| number` | - | 标识 | | header | `string \| SchemaNode` | - | 标题 | | body | `string \| SchemaNode` | - | 内容 | | showArrow | `boolean` | `true` | 是否展示图标 | ## Collapse 事件表当前组件会对外派发以下事件，可以通过 onEvent 来监听这些事件，并通过 actions 来配置执行的动作，在 actions 中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据，详细查看事件动作。 | 事件名称 | 事件参数 | 说明 | | -------- | ------------------------------- | ------------------------ | | change | `collapsed: boolean` 折叠器状态 | 折叠器折叠状态改变时触发 | ### change 折叠面板折叠状态改变时触发。 ```schema: scope="body" { "type": "collapse", "header": "标题", "body": [ { "type": "tpl", "tpl": "内容", "wrapperComponent": "", "inline": false, "id": "u:6588c12ee3b0" } ], "id": "u:62aa2f0c7fd9", "onEvent": { "change": { "weight": 0, "actions": [ { "actionType": "toast", "args": { "msgType": "info", "position": "top-right", "closeButton": true, "showIcon": true, "title": "collapsedChange", "msg": "collapsed: ${event.data.collapsed}", "className": "theme-toast-action-scope" } } ] } } } ``` --- ### Zh CN Components Color (`docs/zh-CN/components/color.md`) --- title: Color 颜色 description: type: 0 group: ⚙ 组件 menuName: Color icon: order: 37 --- 用于展示颜色 ## 基本用法 ```schema { "type": "page", "body": { "type": "color", "value": "#108cee" } } ``` ## 用作 Field 时当用在 Table 的列配置 Column、List 的内容、Card 卡片的内容和表单的 Static-XXX 中时，可以设置`name`属性，映射同名变量 ### Table 中的列类型 ```schema: scope="body" { "type": "table", "data": { "items": [ { "id": "1", "color": "#108cee" }, { "id": "2", "color": "#f38900" }, { "id": "3", "color": "#04c1ba" } ] }, "columns": [ { "name": "id", "label": "Id" }, { "name": "color", "label": "颜色", "type": "color" } ] } ``` List 的内容、Card 卡片的内容配置同上 ### Form 中静态展示 ```schema: scope="body" { "type": "form", "data": { "color": "#108cee" }, "body": [ { "type": "static-color", "name": "color", "label": "颜色" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | | ------------------------ | --------- | ------ | -------------------------------------------------------------------------------------- | ------- | | type | `string` | | 如果在 Table、Card 和 List 中，为`"color"`；在 Form 中用作静态展示，为`"static-color"` | | className | `string` | | 外层 CSS 类名 | | value | `string` | | 显示的颜色值 | | name | `string` | | 在其他组件中，时，用作变量映射 | | defaultColor | `string` | | 默认颜色值 | | showValue | `boolean` | `true` | 是否显示右边的颜色值 | | popOverContainerSelector | `string` | | 弹层挂载位置选择器，会通过`querySelector`获取 | `6.4.2` | --- ### Zh CN Components Container (`docs/zh-CN/components/container.md`) --- title: Container 容器 description: type: 0 group: ⚙ 组件 menuName: Container 容器 icon: order: 38 --- Container 是一种容器组件，它可以渲染其他 amis 组件。注意 Container 组件因为历史原因多了一层 div，推荐使用 [wrapper](wrapper) 来作为容器。 ## 基本用法 ```schema: scope="body" { "type": "container", "body": "这里是容器内容区" } ``` ### style container 可以通过 style 来设置样式，比如背景色或背景图，注意这里的属性是使用驼峰写法，是 `backgroundColor` 而不是 `background-color`。 ```schema: scope="body" { "type": "container", "style": { "backgroundColor": "#C4C4C4" }, "body": "这里是容器内容区" } ``` ### wrapperComponent 修改标签名可以让容器使用其它标签渲染，比如 `pre` ```schema: scope="body" { "type": "container", "wrapperComponent": "pre", "body": "var a = 1;" } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------------- | ----------------------------------------- | ------------- | ----------------------- | | type | `string` | `"container"` | 指定为 container 渲染器 | | className | `string` | | 外层 Dom 的类名 | | bodyClassName | `string` | | 容器内容区的类名 | | wrapperComponent | `string` | `"div"` | 容器标签名 | | style | `Object` | | 自定义样式 | | body | [SchemaNode](../../docs/types/schemanode) | | 容器内容 | ## 事件表 > 3.3.0 及以上版本当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ---------- | -------- | -------------- | | click | - | 点击时触发 | | mouseenter | - | 鼠标移入时触发 | | mouseleave | - | 鼠标移出时触发 | ### click 鼠标点击。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "container", "body": "这里是容器内容区", "onEvent": { "click": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseenter 鼠标移入。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "container", "body": "这里是容器内容区", "onEvent": { "mouseenter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` ### mouseleave 鼠标移出。可以尝试通过`${event.context.nativeEvent}`获取鼠标事件对象。 ```schema: scope="body" { "type": "container", "body": "这里是容器内容区", "onEvent": { "mouseleave": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.context.nativeEvent.type}" } } ] } } } ``` --- ### Zh CN Components Crud (`docs/zh-CN/components/crud.md`) --- title: CRUD 增删改查 description: type: 0 group: ⚙ 组件 menuName: CRUD 增删改查 icon: order: 25 --- CRUD，即增删改查组件，主要用来展现数据列表，并支持各类【增】【删】【改】【查】等操作。注意 CRUD 所需的数据必须放 items 中，因此如果只是想显示表格类型的数据没有分页，请使用 [Table](./table)。 ## 基本用法最基本的用法是配置 **数据源接口(api)** 以及 **展示列(columns)** ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 数据源接口 ### 数据结构 CRUD 组件对数据源接口的数据结构要求如下： - `items`或`rows`：用于返回数据源数据，格式是数组 - `total`或`count`: 用于返回数据库中一共有多少条数据，用于生成分页 ```json { "status": 0, "msg": "", "data": { "items": [ { // 每一行的数据 "id": 1, "xxx": "xxxx" } ], "total": 200 // 注意！！！这里不是当前请求返回的 items 的长度，而是数据库中一共有多少条数据，用于生成分页组件 // 如果你不想要分页，把这个不返回就可以了。 } } ``` 如果想要通过接口控制当前所处在第几页，可以返回字段 `page`（或自定义字段 `pageField` 的值）。 ```json { "status": 0, "msg": "", "data": { "items": [ { // 每一行的数据 "id": 1, "xxx": "xxxx" } ], "total": 200, "page": 20 } } ``` 如果无法知道数据总数，只能知道是否有下一页，请返回如下格式，amis 会简单生成一个简单版本的分页控件。 ```json { "status": 0, "msg": "", "data": { "items": [ { // 每个成员的数据。 "id": 1, "xxx": "xxxx" } ], "hasNext": true // 是否有下一页。 } } ``` 如果不需要分页，或者配置了 `loadDataOnce` 则可以忽略掉 `total` 和 `hasNext` 参数。 ### Query 参数数据源接口地址可以通过变量实现动态拼接，例如： `/api/mock2/sample/${id}`，但需要注意的是接口地址拼接变量后，amis 就不会自动追加默认参数了，例如：分页参数、查询参数等，如需追加，可以自行拼接，例如： `/api/mock2/sample/${id}?page=${page}&perPage=${perPage}` 默认的分页参数是 `page` 和 `perPage`，page 代表页数，比如第一页，perPage 代表每页显示几行。如果要其它格式，比如转成 `limit` 和 `offset`，可以使用公式来转换，比如 `/api/mock2/sample?limit=${perPage}&offset=${(page - 1) * perPage}` ### 参数汇总这里汇总一下 CRUD 里默认用到的 query 列表 | query 名 | 类型 | 说明 | | -------- | ------------ | ------------------------------ | | page | number | 分页，从 1 开始 | | perPage | number | 每页数量 | | orderBy | string | 排序字段，目前 CRUD 只支持一个 | | orderDir | 'asc'/'desc' | 排序方式 | | keywords | string | 搜索关键字 | ### 解析 Query 原始类型 > `3.5.0`及以上版本 `syncLocation`开启后，CRUD 在初始化数据域时，将会对 url 中的 Query 进行转换，将原始类型的字符串格式的转化为同位类型。`3.6.0`版本后支持对象格式，该配置默认开启，且默认仅转化布尔值。 #### ParsePrimitiveQueryOptions ```typescript interface ParsePrimitiveQueryOptions { parsePrimitiveQuery: { enable: boolean; types?: ('boolean' | 'number')[]; }; } ``` 比如开启设置 `{"parsePrimitiveQuery": {"enable": true, "types": ["boolean", "number"]}}` 后： ``` "true" ==> true "false" ==> false "123" ==> 123 "123.4" ==> 123.4 ``` 如果只想保持字符串格式，可以设置`"parsePrimitiveQuery": false` 或者 `"parsePrimitiveQuery": {"enable": false}` 关闭该特性，具体效果参考[示例](../../../examples/crud/parse-primitive-query)。如果想实现字段定制化转化类型，可以使用[配置 API 请求数据](../../docs/types/api#配置请求数据)，通过表达式控制接口传递的参数类型。 ## 功能既然这个渲染器叫增删改查，那接下来分开介绍这几个功能吧。 ### 增其实这个渲染器并没有包含新增功能，新增功能其实还是依靠其他位置放个弹框表单完成，弹框完事了会自动让页面里面的 CRUD 刷新如： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 当然如果你不想要自动刷新，那么给按钮配置 reload: "none" 就行了。 ### 删删除功能主要有三种实现：[单条操作](#单条操作)、[批量操作](#批量操作)或者直接添加一个操作栏，在里面放个类型为 ajax 类型的按钮即可。在这个按钮里面能获得对应的行数据，而且完成后也会自动刷新这个 CRUD 列表。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample?orderBy=id&orderDir=desc", "syncLocation": false, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "type": "operation", "label": "操作", "buttons": [ { "label": "删除", "type": "button", "actionType": "ajax", "level": "danger", "confirmText": "确认要删除？", "api": "delete:/api/mock2/sample/${id}" } ] } ] } ``` ### 改改和删其实是差不多的，唯一的区别在于，配置不同的 api，按钮类型改成弹框。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 弹框里面可用数据自动就是点击的那一行的行数据，如果列表没有返回，可以在 form 里面再配置个 initApi 初始化数据，如果行数据里面有倒是不需要再拉取了。表单项的 name 跟数据 key 对应上便自动回显了。默认发送给表单的保存接口只会包含配置了的表单项，如果不够，请在 api 上配置数据映射，或者直接添加 hidden 类型的表单项（即隐藏域 input[type=hidden]）。 ### 查除了列表查询外，还支持查看详情场景，与编辑不同的地方主要在于弹窗中改成放展示类组件，或者表单项配置静态展示。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 弹框里面可用数据自动就是点击的那一行的行数据，如果列表没有返回，可以在 form 里面再配置个 initApi 初始化数据，如果行数据里面有倒是不需要再拉取了。表单项的 name 跟数据 key 对应上便自动回显了。 ## 展示模式 CRUD 支持下面 3 种展示模式，默认为 Table 表格模式。 ### Table 表格模式 Table 模式支持 [Table](./table) 中的所有功能。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" } ] } ``` 这个模式下会默认开启固定表头功能，如果不需要可以使用 `"affixHeader": false` 关闭。 ### List 列表模式 List 模式支持 [List](./list) 中的所有功能。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/crud/permissions", "mode": "list", "placeholder": "当前组内, 还没有配置任何权限.", "syncLocation": false, "title": null, "listItem": { "title": "$name", "subTitle": "$description", "actions": [ { "icon": "fa fa-edit", "className": "mr-4", "tooltip": "编辑", "actionType": "dialog", "dialog": { "title": "编辑能力（权限）", "body": { "type": "form", "body": [ { "type": "hidden", "name": "id" }, { "name": "name", "label": "权限名称", "type": "input-text", "disabled": true }, { "type": "divider" }, { "name": "description", "label": "描述", "type": "textarea" } ] } } }, { "tooltip": "删除", "disabledOn": "~[\"admin:permission\", \"admin:user\", \"admin:role\", \"admin:acl\", \"admin:page\", \"page:readAll\", \"admin:settings\"].indexOf(name)", "icon": "fa fa-times", "confirmText": "您确定要移除该权限?", "actionType": "ajax", "api": "delete:/api/mock2/notFound" } ] } } ``` ### Cards 卡片模式 Cards 模式支持 [Cards](./cards) 中的所有功能。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 嵌套当行数据中存在 `children` 字段时，CRUD 会自动识别为树形数据，并支持展开收起。 ```schema: scope="body" { "type": "crud", "name": "crud", "syncLocation": false, "api": "/api/mock2/crud/table2", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" } ] } ``` ## 嵌套懒加载如果数据量比较大不适合一次性加载，可以配置 `deferApi` 接口，结合行数据中标记 `defer: true` 属性，实现懒加载。注意 `deferApi` 结果返回跟 `api` 返回不一样，`deferApi` 返回的是节点详情，而不是列表，列表应该是节点信息的 children 属性里面。也就是说 deferApi 还可以进一步完善节点信息。返回格式参考如下： ``` { status: 0, data: { id: 1, xxxProp: 'abc', children: [ { id: 11, name: '子节点' } ] } } ``` ```schema: scope="body" { "type": "crud", "name": "crud", "syncLocation": false, "api": "/api/mock2/crud/table6", "deferApi": "/api/mock2/crud/table6?parentId=${id}", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" } ] } ``` ## 查询条件表单大部分表格展示有对数据进行检索的需求，CRUD 自身支持通过配置`filter`，实现查询条件过滤表单。`filter` 配置实际上同 [Form](./form/index) 组件，因此支持绝大部分`form`的功能。在条件搜索区的 `Engine` 输入框中输入任意值查询会发现结果中 `ID` 为 1 - 3 的 `Rendering engine` 列因为返回值中没有对应字段值，被错误填入了与 `filter` 中相同 `name` 的字段值，这是因为表格 Cell 通过[数据链](../../docs/concepts/datascope-and-datachain)获取到了上层数据域 `filter` 中相同字段的数据值。这种情况可以在 CRUD `columns` 对应列配置`"canAccessSuperData": false`禁止访问父级数据域（比如: `Platform`列），或者 CRUD 追加`"canAccessSuperData": false`配置禁止所有列访问父级数据域。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` **请注意**：在默认没有自定义配置 api 数据映射时，提交查询条件表单，会自动将表单中的表单项值，发送给`crud`所配置的接口，然后通过后端接口，实现对数据的过滤操作，前端默认是不会进行任何的数据过滤操作如果想前端实现过滤功能，请看[前端一次性加载](#前端一次性加载)部分。 ### 自动生成查询区域通过设置`"autoGenerateFilter": true`开启查询区域，会根据列元素的 `searchable` 属性值，自动生成查询条件表单，只有 `searchable` 属性值为合法的组件 Schema 时才会生成查询条件。注意这个属性和 `filter` 冲突，开启 `filter` 后 `autoGenerateFilter` 将会失效。 ### autoGenerateFilter 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------------- | --------- | ------ | -------------------- | | columnsNum | `number` | `3` | 过滤条件单行列数 | | showBtnToolbar | `boolean` | `true` | 是否显示设置查询字段 | | defaultCollapsed | `boolean` | `true` | 是否初始收起 | ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 多个列表共用一套查询条件如果希望一个查询表单作用在多个列表中，可以直接 `form + n * crud` 的方式。将 form 的提交目标给到多个 crud。 > 注意：如果一个页面有多个 crud，请控制同步地址栏的 crud 数量不要超过一个。否则会相互干扰 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 配置默认请求参数可以配置`defaultParams`，来指定拉取接口时的默认参数： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "defaultParams": { "perPage": 50 }, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 例如上例中，配置`{ perPage: 50 }`，指定分页的默认每页数据条数为 50 条。 ## 数据源接口轮询可以配置`interval`来实现数据接口轮询功能，最低为`1000`毫秒： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "interval": 3000, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 配置`stopAutoRefreshWhen`表达式，来实现满足条件，停止轮询 ## 列配置除了支持 [Table 中的列配置](./table#%E5%88%97%E9%85%8D%E7%BD%AE) 以外，crud 还支持下面这些配置，帮助更好的操作数据 ### 排序检索可以在列上配置`"sortable": true`，该列表头右侧会渲染一个可点击的排序图标，可以切换`正序`和`倒序`。 > 如果想默认就基于某个字段排序，可以结合 `defaultParams` 一起配置。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "defaultParams": { "orderBy": "engine", "orderDir": "desc" }, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "sortable": true } ] } ``` amis 只负责生成排序组件，并将排序参数传递给接口，而不会在前端对数据进行排序处理。参数格式如下： ```json { "orderBy": "engine", // 这里为所配置列的 name "orderDir": "asc" // asc 为升序，desc 为降序 } ``` 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。 ### 快速搜索可以在列上配置`"searchable": true`，该列表头右侧会渲染一个可点击的搜索图标，点击可以输入关键字进行该列的搜索： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "searchable": true } ] } ``` 也可以通过`searchable`来自定义搜索表单 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "searchable": { "type": "form", "wrapWithPanel": false, "body": [ { "type": "input-text", "name": "engine" } ] } } ] } ``` amis 只负责生成搜索组件，并将搜索参数传递给接口，而不会在前端对数据进行搜索处理。参数格式如下： ```json { "engine": "xxx" // 这里的key是列的 name，value是输入的关键字 } ``` 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。 ### 快速过滤可以在列上配置`filterable`属性，该列表头右侧会渲染一个可点击的过滤图标，点击显示下拉框，选中进行过滤： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "filterable": { "options": [ "A", "B", "C", "D", "X" ] } }, { "name": "version", "label": "Version", "filterable": { "options": [ {"label": "0", "value": 0}, {"label": "1", "value": 1} ] } } ] } ``` amis 只负责生成下拉选择器组件，并将搜索参数传递给接口，而不会在前端对数据进行搜索处理。参数格式如下： ```json { "grade": "xxx" // 这里的key是列的 name，value是选中项的value值 } ``` 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。 #### 快速过滤支持检索 > 3.7.0 及以上版本通过配置 `searchable` 支持选项检索 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "filterable": { "searchable": true, "options": [ "A", "B", "C", "D", "X" ] } } ] } ``` 如果需要更细节的配置，可以使用 `searchConfig`，详细配置项参考 search-box 组件 #### 下拉数据源过滤器的数据域支持 API 接口和上下文数据(`3.6.0`及以上版本) ```schema { "type": "page", "data": { "options": [ {"label": "4", "value": 3}, {"label": "5", "value": 5}, {"label": "5.5", "value": 5.5}, {"label": "6", "value": 6} ] }, "body": [ { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "filterable": { "source": "/api/mock2/crud/filterOptions" } }, { "name": "version", "label": "Version", "filterable": { "source": "${options}" } } ] } ] } ``` ### 快速编辑可以通过给列配置：`"quickEdit":true`和`quickSaveApi` 可以实现表格内快速编辑并批量保存的功能。如下`Rendering engine`列的每一行中，会生成可编辑图标，点击后会显示弹框，用于编辑该列的值， ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "quickEdit":true } ] } ``` #### 指定编辑表单项类型 `quickEdit`也可以配置对象形式，可以指定编辑表单项的类型，例如`"type": "select"`： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "type": "select", "options": [ "A", "B", "C", "D", "X" ] } } ] } ``` #### 快速编辑多个表单项 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "body": [ { "type": "select", "name": "grade", "options": [ "A", "B", "C", "D", "X" ] }, { "label": "id", "type": "input-text", "name": "id" } ] } } ] } ``` #### 内联模式配置`quickEdit`的`mode`为`inline`。可以直接将编辑表单项渲染至表格内，可以直接操作编辑。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "mode": "inline", "type": "select", "size": "xs", "options": [ "A", "B", "C", "D", "X" ] } }, { "name": "switch", "label": "switch", "quickEdit": { "mode": "inline", "type": "switch", "onText": "开启", "offText": "关闭" } } ] } ``` #### 即时保存如果想编辑完表单项之后，不想点击顶部确认按钮来进行保存，而是即时保存当前标记的数据，则需要配置 `quickEdit` 中的 `"saveImmediately": true`，然后配置接口`quickSaveItemApi`，可以直接将编辑表单项渲染至表格内操作。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveItemApi": "/api/mock2/sample/$id", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "mode": "inline", "type": "select", "size": "xs", "options": [ "A", "B", "C", "D", "X" ], "saveImmediately": true } }, { "name": "switch", "label": "switch", "quickEdit": { "mode": "inline", "type": "switch", "onText": "开启", "offText": "关闭", "saveImmediately": true, "resetOnFailed": true } } ] } ``` 你也可以在`saveImmediately`中配置 api，实现即时保存 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "mode": "inline", "type": "select", "size": "xs", "options": [ "A", "B", "C", "D", "X" ], "saveImmediately": { "api": "/api/mock2/sample/$id" } } }, { "name": "grade", "label": "CSS grade", "quickEdit": { "mode": "inline", "type": "switch", "onText": "开启", "offText": "关闭", "saveImmediately": true } } ] } ``` #### 配置快速编辑启动条件通过 `quickEditEnabledOn` 配置表达式来实现，如下，只有 id 小于 5 的数据可以编辑 engine。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "quickEdit":true, "quickEditEnabledOn": "this.id < 5" } ] } ``` ## 顶部和底部工具栏 crud 组件支持通过配置`headerToolbar`和`footerToolbar`属性，实现在表格顶部和底部渲染组件， ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ { "type": "tpl", "tpl": "一共有${count}条数据" } ], "footerToolbar": [ { "type": "action", "actionType": "dialog", "label": "底部工具栏按钮", "dialog": { "title": "一个弹框", "body": { "type": "tpl", "tpl": "一个简单的弹框" } } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 上例中我们在顶部渲染了一段模板，通过`${count}`取到数据域中，CRUD 返回的`count`变量值；然后我们在底部渲染了一个按钮。从上面一些例子中你可能已经发现，当我们不配置该属性时，crud 默认会在顶部和底部渲染一些组件，实际上，`headerToolbar`和`footerToolbar`默认会有下面这些配置： ```json { "headerToolbar": ["bulkActions", "pagination"], "footerToolbar": ["statistics", "pagination"] } ``` - 在顶部工具栏中：渲染批量操作按钮（如果在 crud 中，配置了 bulkActions 的话）和分页组件 - 在底部工具栏中：渲染数据统计组件和分页组件 > 如果你不希望在顶部或者底部渲染默认组件，你可以设置`headerToolbar`和`footerToolbar`为空数组`[]` 这些组件还能设置 `align` 来控制位置，有 `left` 和 `right` 两种，比如 ```json { "headerToolbar": [ { "type": "bulkActions", "align": "right" } ] } ``` ### 其它 amis 组件在 `headerToolbar` 和 `footerToolbar` 中可以配置各种 amis 其它组件，比如按钮和 tpl： ```schema: scope="body" { "type": "crud", "name": "myCRUD", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ { "label": "点击弹框", "type": "button", "actionType": "dialog", "icon": "fa fa-plus", "level": "primary", "dialog": { "title": "弹框标题", "body": "这是一个弹框" } }, { "type": "tpl", "tpl": "自定义模板" }, { "label": "", "icon": "fa fa-repeat", "type": "button", "actionType": "reload", "target": "myCRUD", "align": "right" } ], "footerToolbar": [], "columns": [ { "name": "id", "label": "ID" } ] } ``` ### 分页在`headerToolbar`或者`footerToolbar`数组中添加`pagination`字符串，并且在数据源接口中返回了数据总数`count`，即可以渲染分页组件；添加`switch-per-page`字符串，可以渲染切换每页条数组件 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [], "footerToolbar": ["switch-per-page", "pagination"], "columns": [ { "name": "id", "label": "ID" }, { "name": "grade", "label": "CSS grade", "quickEdit": { "mode": "inline", "type": "select", "size": "xs", "options": [ "A", "B", "C", "D", "X" ], "saveImmediately": { "api": "/api/mock2/sample/$id" } } } ] } ``` `crud`默认不会处理数据分页，只是会把分页参数传给后端，由后端实现分页，并返回需要展示的数据和总数据数`total`变量：默认传给后端的分页参数格式为： ```json { "page": 1, "perPage": 10 } ``` 你可以通过配置`pageField`和`perPageField`来修改传给后端的分页数据格式，如： ```json { "pageField": "pageNo", "perPageField": "pageSize" } ``` 这样传给后端的参数格式将为： ```json { "pageNo": 1, "pageSize": 10 } ``` 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。 ```json { "type": "crud", "api": { "method": "get", "url": "xxxxxx", "data": { "pageNo": "${page}", "pageSize": "${perPage}", ... // 一些其他参数 } } } ``` 分页有两种模式： **1. 知道数据总数** 如果后端可以知道数据总数时，接口返回格式如下： ```json { "status": 0, "msg": "", "data": { "items": [ { // 每一行的数据。 "id": 1, "xxx": "xxxx" } ], "total": 200 // 注意这里不是当前请求返回的 items 的长度，而是数据库一共有多少条数据，用于生成分页， } } ``` 该模式下，会自动计算总页码数，渲染出有页码的分页组件 **2. 不知道数据总数** 如果后端无法知道数据总数，那么可以返回`hasNext`字段，来标识是否有下一页。 ```json { "status": 0, "msg": "", "data": { "items": [ { // 每个成员的数据。 "id": 1, "xxx": "xxxx" } ], "hasNext": true // 标识是否有下一页。 } } ``` 这样 amis 会在配置分页组件的地方，渲染出一个简单的页面跳转控件。 > 如果总数据只够展示一页，则默认不显示该分页组件 #### 前端分页如果你的数据并不是很大，而且后端不方便做分页和条件过滤操作，那么通过配置`loadDataOnce`实现前端一次性加载并支持分页和条件过滤操作。

温馨提示开启loadDataOnce后，搜索和过滤将交给组件处理，默认对所有字段采用模糊匹配（比如：mi将会匹配amis）。如果首次加载数据时设置了预设条件，导致接口返回的数据集合未按照此规则过滤，则可能导致切换页码后分页错误。此时有2种方案处理： 1. 将接口返回的列表数据按照所有字段模糊匹配的规则处理 2. 配置matchFunc，自定义处理过滤

```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "loadDataOnce": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "sortable": true } ] } ``` 配置一次性加载后，基本的分页、快速排序操作将会在前端进行完成。如果想实现前端检索(目前是模糊搜索)，可以在 table 的 `columns` 对应项配置 `searchable` 来实现。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "loadDataOnce": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version", "searchable": { "type": "select", "name": "version", "label": "Engine version", "clearable": true, "multiple": true, "searchable": true, "checkAll": true, "options": ["1.7", "3.3", "5.6"], "maxTagCount": 10, "extractValue": true, "joinValues": false, "delimiter": ',', "defaultCheckAll": false, "checkAllLabel": "全选" } }, { "name": "grade", "label": "CSS grade" } ] } ``` > **注意：**如果你的数据量较大，请务必使用服务端分页的方案，过多的前端数据展示，会显著影响前端页面的性能另外前端一次性加载当有查寻条件的时候，默认还是会重新请求一次，如果配置 `loadDataOnceFetchOnFilter` 为 `false` 则为前端过滤。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "loadDataOnce": true, "loadDataOnceFetchOnFilter": false, "autoGenerateFilter": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version", "searchable": { "type": "select", "name": "version", "label": "Engine version", "clearable": true, "multiple": true, "searchable": true, "checkAll": true, "options": [ "1.7", "3.3", "5.6" ], "maxTagCount": 10, "extractValue": true, "joinValues": false, "delimiter": ",", "defaultCheckAll": false, "checkAllLabel": "全选" } }, { "name": "grade", "label": "CSS grade" } ] } ``` `loadDataOnceFetchOnFilter` 配置成 `true` 则会强制重新请求接口比如以下用法 > 此时如果不配置或者配置为 `false` 是前端直接过滤，不过记得配置 name 为行数据中的属性，如果行数据中没有对应属性则不会起作用 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "loadDataOnce": true, "loadDataOnceFetchOnFilter": true, "headerToolbar": [ { "type": "search-box", "name": "keywords" } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version", "searchable": { "type": "select", "name": "version", "label": "Engine version", "clearable": true, "multiple": true, "searchable": true, "checkAll": true, "options": [ "1.7", "3.3", "5.6" ], "maxTagCount": 10, "extractValue": true, "joinValues": false, "delimiter": ",", "defaultCheckAll": false, "checkAllLabel": "全选" } }, { "name": "grade", "label": "CSS grade" } ] } ``` ##### 匹配函数 > `3.5.0` 及以上版本支持自定义匹配函数`matchFunc`，当开启`loadDataOnce`时，会基于该函数计算的匹配结果进行过滤，主要用于处理列字段类型较为复杂或者字段值格式和后端返回不一致的场景，函数签名如下： ```typescript interface CRUDMatchFunc { ( /* 当前列表的全量数据 */ items: any, /* 最近一次接口返回的全量数据 */ itemsRaw: any, /** 相关配置 */ options?: { /* 查询参数 */ query: Record; /* 列配置 */ columns: any; /** match-sorter 匹配函数 */ matchSorter: ( items: any[], value: string, options?: MatchSorterOptions ) => any[]; } ): boolean; } ``` 具体效果请参考[示例](../../../examples/crud/match-func)，从`3.6.0`版本开始，`options`中支持使用`matchSorter`函数处理复杂的过滤场景，比如前缀匹配、模糊匹配等，更多详细内容推荐查看[match-sorter](https://github.com/kentcdodds/match-sorter)。 ### 显示序号通过配置 `showIndex` 为 `true` 启用 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "loadDataOnce": true, "showIndex": true, "columns": [ { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "sortable": true } ] } ``` ### 批量操作在`headerToolbar`或者`footerToolbar`数组中添加`bulkActions`字符串，并且在 crud 上配置`bulkActions`行为按钮数组，可以实现选中表格项并批量操作的功能。 > 需要设置`primaryField`用于标识选中状态，配置当前行数据中的某一**唯一标识字段**，例如`id`，否则可能会出现无法选中的问题 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 批量操作数据域批量操作会默认将下面数据添加到数据域中以供**按钮行为**使用，需要注意的是**静态**和**批量操作**时的数据域是不同的。**静态数据域**是指渲染批量操作区域时能够获取到的数据，**批量操作数据域**是指触发按钮动作时能够获取到的数据，具体区别参考下表： | 属性名 | 类型 | 所属数据域 | 说明 | 版本 | | ----------------- | ------------------------- | -------------- | ------------------------------------------------------------------------------------ | ------- | | `currentPageData` | `Array` | 静态, 批量操作 | 当前分页数据集合，`Column`为当前 Table 数据结构定义 | `2.4.0` | | `selectedItems` | `Array` | 静态, 批量操作 | 选中的行数据集合 | | `selectedIndexes` | `Array` | 静态, 批量操作 | 选中的行数据索引集合 | | `unSelectedItems` | `Array` | 静态, 批量操作 | 未选中的行数据集合 | | `items` | `Array` | 批量操作 | `selectedItems` 的别名 | | `rows` | `Array` | 批量操作 | `selectedItems` 的别名，推荐用 `items` | | `ids` | `string` | 批量操作 | 多个 id 值用英文逗号隔开，前提是行数据中有 id 字段，或者有指定的 `primaryField` 字段 | | `event` | `object` | 事件动作 | 可以通过`event.data`获取批量操作按钮上绑定的事件动作产生的数据 | | `...rest` | `Record` | 批量操作 | 选中的行数据集合的首个元素的字段，注意列字段如果和以上字段重名时，会被上述字段值覆盖 | 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。 **约束批量操作** 有时候并不是勾选了就能支持批量操作的，比如想约束如果勾选了某条数据 owner 值不是当前用户的就不可以操作。有两种方式来约束。 1. 批量操作按钮上配置 `disabledOn` 值为 `this.selectedItems.some(item => item.owner === this.amisUser.name)` 2. 给表格加上 `itemCheckableOn` 值为 `this.owner === this.amisUser.name` 表示只有 owner 是自己的才可以打勾。 **保留条目选择** 默认分页、搜索后，用户选择条目会被清空，配置`keepItemSelectionOnPageChange`属性后会保留用户选择，可以实现跨页面批量操作。同时可以通过配置`maxKeepItemSelectionLength`属性限制最大勾选数 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ "bulkActions" ], "keepItemSelectionOnPageChange": true, "maxKeepItemSelectionLength": 4, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" }, { "label": "批量修改", "actionType": "dialog", "dialog": { "title": "批量编辑", "body": { "type": "form", "api": "/api/mock2/sample/bulkUpdate2", "body": [ { "type": "hidden", "name": "ids" }, { "type": "input-text", "name": "engine", "label": "Engine" } ] } } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` **当前页最大勾选数** 如果不需要在分页、搜索后，保留用户选择，即不需要配置`keepItemSelectionOnPageChange`，可以通过配置`maxItemSelectionLength`属性限制当前页条目的最大勾选数 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ "bulkActions" ], "maxItemSelectionLength": 4, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" }, { "label": "批量修改", "actionType": "dialog", "dialog": { "title": "批量编辑", "body": { "type": "form", "api": "/api/mock2/sample/bulkUpdate2", "body": [ { "type": "hidden", "name": "ids" }, { "type": "input-text", "name": "engine", "label": "Engine" } ] } } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ], "itemCheckableOn": "this.index !== 2" } ``` `maxItemSelectionLength`也可以和`keepItemSelectionOnPageChange`搭配使用，起到和`maxKeepItemSelectionLength`一样的效果 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ "bulkActions" ], "keepItemSelectionOnPageChange": true, "maxItemSelectionLength": 4, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" }, { "label": "批量修改", "actionType": "dialog", "dialog": { "title": "批量编辑", "body": { "type": "form", "api": "/api/mock2/sample/bulkUpdate2", "body": [ { "type": "hidden", "name": "ids" }, { "type": "input-text", "name": "engine", "label": "Engine" } ] } } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ], "itemCheckableOn": "this.index !== 2 && this.index !== 5" } ``` 还可以设置 `"checkOnItemClick": true` 属性来支持点击一行的触发选中状态切换 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 悬浮操作栏通过配置 `itemActions` 可以启用悬浮操作栏，鼠标悬停到行上，右侧会出现对应的操作按钮。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "checkOnItemClick": true, "itemActions": [ { "type": "button", "label": "按钮 1", "actionType": "toast", "toast": { "items": [ { "level": "info", "body": "${&|json}" } ] } }, { "type": "button", "label": "按钮 2", "actionType": "toast", "toast": { "items": [ { "level": "info", "body": "${&|json}" } ] } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 当同时配置 `itemActions` 和 `bulkActions`, 顶部工具栏会根据选择的条数来切换显示按钮。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 如果同时启用时，只想把按钮展示在顶部，而不是悬浮，则需要给按钮上配置 `hiddenOnHover`。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 数据统计在`headerToolbar`或者`footerToolbar`数组中添加`statistics`字符串，可以实现简单的数据统计功能 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": ["statistics"], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ### 加载更多在`headerToolbar`或者`footerToolbar`数组中添加`load-more`字符串，可以实现点击加载更多功能。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": ["load-more"], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ### 导出 CSV 在`headerToolbar`或者`footerToolbar`数组中添加`export-csv`字符串，可以实现点击下载 CSV 的功能，注意这里只包括当前分页的数据，要下载全部数据需要通过后端 API 实现。 > 注意：导出 CSV 时，默认使用 CRUD 的接口数据，不导出「操作」列 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": ["export-csv"], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "type": "mapping", "map": { "*": "${grade}" } } ] } ``` #### 通过 api 导出 CSV > 1.4.0 及以上版本 `export-csv` 可以单独配置 `api` 实现导出全量功能，这个 api 的返回结果和 CRUD 类似 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ { "type": "export-csv", "label": "全量导出 CSV", "api": "/api/mock2/sample" } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "type": "mapping", "map": { "*": "${grade}" } } ] } ``` #### 自定义导出 CSV 的文件名 > 1.4.0 及以上版本 `export-csv` 可以单独配置 `api` 实现导出全量功能，这个 api 的返回结果和 CRUD 类似 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "data": { "name": "123" }, "headerToolbar": [ { "type": "export-csv", "label": "自定义导出 CSV", "api": "/api/mock2/sample", "filename": "自定义文件名${name}" } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "type": "mapping", "map": { "*": "${grade}" } } ] } ``` ### 导出 Excel 在`headerToolbar`或者`footerToolbar`数组中添加`export-excel`字符串，可以实现点击下载 Excel 的功能，和导出 CSV 一样只包括当前分页的数据，但它们有明显区别： 1. 导出 CSV 是将 api 返回数据导出，表头是数据里的 key，而 Excel 的表头使用的是 label。 2. 导出 Excel 更重视展现一致，支持合并单元格、链接、mapping 映射、图片（需要加[跨域 Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)）。 3. 导出 Excel 只在 `mode` 为 `table` 时能用。 > 注意：导出 Excel 时，默认不导出「操作」列 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": ["export-excel"], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade", "type": "mapping", "map": { "*": "${grade}" } } ] } ``` #### 只导出部分列 > 1.4.0 及以上版本通过配置 `columns` 来支持只导出部分列，其中是需要导出的列 `name` 数组 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [{ "type": "export-excel", "label": "只导出 engine 和 browser 列", "columns": ["engine", "browser"] }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` > 1.8.0 及以上版本 `columns` 支持变量，可以从上下文取数组 ```schema { "type": "page", "data": { "columns": ["engine", "browser"] }, "body": { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [{ "type": "export-excel", "label": "只导出 engine 和 browser 列", "columns": "${columns}" }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` #### 自定义导出列 > 1.8.0 及以上版本除了简单隐藏某些列，还可以通过 `exportColumns` 完全控制导出列，比如新增某些列，它的配置项和 `columns` 一致 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [{ "type": "export-excel", "label": "导出 Excel", "exportColumns": [ { "name": "engine", "label": "Engine" }, { "type": "tpl", "label": "tpl", "tpl": "${browser}" } ] }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` #### 指定导出行 > 3.2.0 及以上版本可以通过配置 `rowSlice` 属性来控制导出哪些行 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [{ "type": "export-excel", "label": "导出 1, 4, 5 行", "rowSlice": "0,3:5" }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` `rowSlice` 支持以下写法 - 取单个值 '1,2,3'，代表取 1、2、3 索引的内容 - 取范围 '3:10'，代表取 3-9 索引的内容 - ':' 代表所有行 - '1:' 代表从第二行开始到结束 - 结束可以是负数 ':-1'，代表除了最后一个元素的所有元素，开始为空代表 0 - 前两种的组合 '1,3:10'，代表取 1 索引和 3-9 索引的内容 #### 通过 api 导出 Excel > 1.1.6 以上版本支持除了前面的用法，还可以配置 api 来通过数据请求来导出 Excel，实现类似全量导出的功能 ```schema: scope="body" { "type": "crud", "syncLocation": false, "headerToolbar": [{ "type": "export-excel", "label": "全量导出 Excel", "api": "/api/mock2/sample" }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` #### 自定义导出 Excel 的文件名 > 1.1.7 以上版本支持通过 filename 自定义导出文件名（支持模板变量） ```schema: scope="body" { "type": "crud", "syncLocation": false, "headerToolbar": [{ "type": "export-excel", "label": "自定义导出 Excel", "filename": "自定义文件名${test}", "api": "/api/mock2/sample" }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ### 导出 Excel 模板 > 6.1 及以上版本配置是 `export-excel-template` 和前面 `export-excel` 不同，这个功能只导出表头，主要用于线下填数据，可以配合 input-excel 组件来上传填好的内容。 ```schema: scope="body" { "type": "crud", "syncLocation": false, "headerToolbar": [{ "type": "export-excel-template", "label": "导出 Excel 模板", }], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ### 显隐显示查询条件表单在`headerToolbar`或者`footerToolbar`数组中添加`filter-toggler`字符串，并且在 crud 中配置`"filterTogglable": true`后，可以渲染一个可以切换显示查询表单的功能按钮 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "filter": { "title": "条件搜索", "body": [ { "type": "input-text", "name": "keywords", "placeholder": "通过关键字搜索" } ] }, "filterTogglable": true, "headerToolbar": [ "filter-toggler" ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 还可以定制文案和按钮如： ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "filter": { "title": "条件搜索", "body": [ { "type": "input-text", "name": "keywords", "placeholder": "通过关键字搜索" } ] }, "filterTogglable": { "label": "更多搜索", "activeLabel": "收起搜索", "icon": "fa fa-arrow-down mr-1", "activeIcon": "fa fa-arrow-up mr-1" }, "headerToolbar": [ "filter-toggler" ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ### 刷新按钮 > 1.5.0 及以上版本可以通过 `reload` 来展现刷新按钮 ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "headerToolbar": [ "reload" ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 它其实是个简化的 `button` 组件，可以参考 `button` 组件的文档做调整。 #### 刷新 CRUD 触发方式触发 CRUD 刷新的方式有 3 种： 1. **reload 类型按钮**：使用`{"type": "reload", ...}`，CRUD 内部会对点击事件做处理 2. **reload 动作按钮**：使用`{"type": "action", "actionType": "reload", "target": "targetName", ...}`，指定`target`为要刷新的 CRUD 组件的`name` 3. **reload 事件动作**：使用[事件动作](../../docs/concepts/event-action)，指定`id`为要刷新的 CRUD 组件的`id` ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 刷新后默认会重置当前已选行数据，即使设置了 `keepItemSelectionOnPageChange` 为 `true`，也会重置。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 总结行如果是默认的表格模式，还支持增加总结行，具体请参考 [table](./table#总结行) 的文档。 ## 弹框与数据链一般 CRUD 中会有弹框，然后进行数据展示或进行二次编辑的需求，通过在列中配置按钮，然后配置弹框，弹框内配置相应的组件即可。现在问题是，如何获取到当前操作行的数据呢？实际上，你操作当前行数据，会成为弹框这层节点的父级节点，因此你可以通过 [数据链](../../docs/concepts/datascope-and-datachain)，获取到上层，也就是点击的行的数据，具体获取方法和普通组件获取数据域中数据的方法相同， ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "draggable": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" }, { "type": "button", "label": "一个弹框", "actionType": "dialog", "dialog": { "title": "一个弹框", "body": [ { "type": "tpl", "tpl": "行数据中 Browser 值为：${browser}" }, { "type": "divider" }, { "type": "form", "api": "/api/mock2/sample/$id", "body": [ { "type": "input-text", "name": "engine", "label": "Engine" } ] } ] } } ] } ``` 例如上例中 Tpl 用 `${browser}` 获取 `browser` 变量，Form 中配置`"name": "engine"` 映射 `engine` 变量。 > 遇到数据字段冲突时，可以在 [弹框上通过配置数据映射](./dialog#%E5%BC%B9%E6%A1%86%E4%B8%8E%E6%95%B0%E6%8D%AE%E6%98%A0%E5%B0%84) 解决。 ## 拖拽排序通过配置`"draggable": true`和保存排序接口`saveOrderApi`，可以实现拖拽排序功能， ```schema: scope="body" { "type": "crud", "syncLocation": false, "api": "/api/mock2/sample", "draggable": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 同样的，前端是不会处理排序结果，需要后端调用接口`saveOrderApi`来保存新的顺序发送方式默认为`POST`，会包含以下信息。 - `ids` 字符串如： `2,3,1,4,5,6` 用 id 来记录新的顺序。前提是你的列表接口返回了 id 字段。另外如果你的 primaryField 不是 `id`，则需要配置如： `primaryField: "order_id"`。注意：无论你配置成什么 primayField，这个字段名始终是 ids。 - `rows` `Array` 数组格式，新的顺序，数组里面包含所有原始信息。 - `insertAfter` 或者 `insertBefore` 这是 amis 生成的 diff 信息，对象格式，key 为目标成员的 primaryField 值，即 id，value 为数组，数组中存放成员 primaryField 值。如： ```json { "insertAfter": { "2": ["1", "3"], "6": ["4", "5"] } } ``` 表示：成员 1 和成员 3 插入到了成员 2 的后面。成员 4 和成员 5 插入到了成员 6 的后面。你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。如下: ```json { "saveOrderApi": { "url": "/api/xxxx", "data": { "ids": "${ids}" } } } ``` 这样就只会发送 ids 了。 ### 列排序通过配置`headerToolbar` 中 `columns-toggler` 的 `"draggable": true`可以实现设置显示列和列排序功能。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "headerToolbar": [ { "type": "columns-toggler", "align": "right", "draggable": true, "icon": "fas fa-cog", "overlay": true, "footerBtnSize": "sm" } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ## 单条操作当操作对象是单条数据时这类操作叫单条操作，比如：编辑、删除、通过、拒绝等等。CRUD 的 table 模式可以在 column 通过放置按钮来完成（其他模式参考 table 模式）。比如编辑就是添加个按钮行为是弹框类型的按钮或者添加一个页面跳转类型的按钮把当前行数据的 id 放在 query 中传过去、删除操作就是配置一个按钮行为是 AJAX 类型的按钮，将数据通过 api 发送给后端完成。 CRUD 中不限制有多少个单条操作、添加一个操作对应的添加一个按钮就行了。CRUD 在处理按钮行为的时候会把当前行的完整数据传递过去，如果你的按钮行为是弹出时，还会包含一下信息： - `hasNext` `boolean` 当按钮行为是弹框时，还会携带这个数据可以用来判断当前页中是否有下一条数据。 - `hasPrev` `boolean` 当按钮行为是弹框时，还会携带这个数据可以判断用来当前页中是否有上一条数据。 - `index` `number` 当按钮行为是弹框时，还会携带这个数据可以用来获取当前行数据在这一页中的位置。 - `prevIndex` `number` - `nextIndex` `number` 你可以通过[数据映射](../../docs/concepts/data-mapping)，在`api`中获取这些参数。如果你的按钮类型是 ajax，你也可以限定只发送部分数据比如。 ```json { "type": "button", "label": "删除", "actionType": "ajax", "api": "delete:/api/xxxx/$id", "confirmText": "确定要删除？" } ``` 上面这个例子就会发送 id 字段了，如果想要全部发送过去同时还想添加点别的字段就这样： ```json { "type": "button", "label": "删除", "actionType": "ajax", "api": { "method": "post", "url": "/api/xxxx/$id", "data": { "&": "$$", "op": "delete" } }, "confirmText": "确定要删除？" } ``` > **注意：** 如果使用`feedback`弹窗，如果不想关闭弹窗时触发`crud`再次拉取数据，需要设置`button`的`"reload":"none"` ## 过滤条件参数同步地址栏默认 CRUD 会将过滤条件参数同步至浏览器地址栏中，比如搜索条件、当前页数，这也做的目的是刷新页面的时候还能进入之前的分页。但也会导致地址栏中的参数数据合并到顶层的数据链中，例如：自动给同名的表单项设置默认值。如果不希望这个功能，可以设置 `syncLocation: false` 来关闭。 > 本文中的例子为了不相互影响都关闭了这个功能。 > 另外如果需要使用接口联动，需要设置`syncLocation: false` `syncLocation`开启后，数据域经过地址栏同步后，原始值被转化为字符串同步回数据域，但布尔值（boolean）同步后不符合预期数据结构，导致组件渲染出错。比如查询条件表单中包含[Checkbox](./form/checkbox)组件，此时可以设置`{"trueValue": "1", "falseValue": "0"}`，将真值和假值设置为字符串格式规避。从`3.5.0`版本开始，已经支持[`parsePrimitiveQuery`](#解析query原始类型)，该配置默认开启。 ## 动态列 > since 1.1.6 在 1.1.6 之前的版本，只能通过 service + schemaApi 让后端返回 schema 配置来实现，1.1.6 版本之后可以直接通过 crud 的数据接口返回了。用这种方式可以简化动态列的实现，与 items 并列返回 columns 数组即即可。 ```schema: scope="body" { "type": "crud", "api": "/api/crud/dynamic?waitSeconds=1" } ``` ## 使用数据链中的数据可以通过 `source` 属性来自定义去返回数据的字段，或者取数据域中的数据，比如 ```schema { "type": "page", "data": { "myItems": [ { "id": 1 } ] }, "body": { "type": "crud", "source": "${myItems}", "columns": [ { "name": "id", "label": "ID" } ] } } ``` ## 自定义点击行的行为 > 1.4.0 及以上版本配置 `itemAction` 可以实现点击某一行后进行自定义操作，支持 [action](./action) 里的所有配置，比如弹框、刷新其它组件等。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "itemAction": { "type": "button", "actionType": "dialog", "dialog": { "title": "详情", "body": "当前行的数据 browser: ${browser}, version: ${version}" } }, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 注意这个属性和 `checkOnItemClick` 冲突，因为都是定义行的点击行为，开启 `itemAction` 后 `checkOnItemClick` 将会失效。 > 1.4.2 及以上版本 itemAction 里的 onClick 还能通过 `data` 参数拿到当前行的数据，方便进行下一步操作 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "itemAction": { "type": "button", "onClick": "console.log(data); alert(data.engine)" }, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ## 开启点选当配置了 `bulkActions` 后，CRUD 会自动变成可点选状态。如果想直接开启可点选，可以配置 `selectable`，同时可以配置 `multiple` 来配置是单选还是多选。但是这个时候没有任何交互，需要配置事件动作，或者在工具栏中添加行为按钮完成交互逻辑。 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "selectable": true, "headerToolbar": [ { "type": "button", "label": "按钮", "visibleOn": "${selectedItems.length}", "actionType": "toast", "toast": { "items": [ { "level": "info", "body": "${selectedItems|json}" } ] } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` 多选场景且支持跨页面选择同时支持快速修改 ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "loadDataOnce": true, "keepItemSelectionOnPageChange": true, "onEvent": { "selectedChange": { "actions": [ { "actionType": "toast", "args": { "msg": "已选择数据 ${selectedItems.length}
未选 ${event.data.unSelectedItems.length} 条
已选 indexes ${ENCODEJSON(selectedIndexes)}" } } ] } }, "bulkActions": [ { "label": "Button(${selectedItems.length})", "type": "button", "onEvent": { "click": { "actions": [ { "actionType": "toast", "args": { "msg": "已选择数据 ${ENCODEJSON(ARRAYMAP(selectedItems, item => `${item.id}: ${item.engine}`))}
未选 ${event.data.unSelectedItems.length} 条
已选 indexes ${ENCODEJSON(selectedIndexes)}" } } ] } } } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine", "quickEdit": true }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | ------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | type | `string` | | `type` 指定为 CRUD 渲染器 | | mode | `string` | `"table"` | `"table" 、 "cards" 或者 "list"` | | title | `string` | `""` | 可设置成空，当设置成空时，没有标题栏 | | className | `string` | | 表格外层 Dom 的类名 | | api | [API](../../docs/types/api) | | CRUD 用来获取列表数据的 api。 | | deferApi | [API](../../docs/types/api) | | 当行数据中有 defer 属性时，用此接口进一步加载内容 | | loadDataOnce | `boolean` | | 是否一次性加载所有数据（前端分页） | | loadDataOnceFetchOnFilter | `boolean` | `true` | 在开启 loadDataOnce 时，filter 时是否去重新请求 api | | source | `string` | | 数据映射接口返回某字段的值，不设置会默认使用接口返回的`${items}`或者`${rows}`，也可以设置成上层数据源的内容 | | filter | [Form](./form/index) | | 设置过滤器，当该表单提交后，会把数据带给当前 `mode` 刷新列表。 | | filterTogglable | `boolean` \| `{label: string; icon: string; activeLabel: string; activeIcon?: string;}` | `false` | 是否可显隐过滤器 | | filterDefaultVisible | `boolean` | `true` | 设置过滤器默认是否可见。 | | initFetch | `boolean` | `true` | 是否初始化的时候拉取数据, 只针对有 filter 的情况, 没有 filter 初始都会拉取数据 | | interval | `number` | `3000` | 刷新时间(最低 1000) | | silentPolling | `boolean` | `false` | 配置刷新时是否隐藏加载动画 | | stopAutoRefreshWhen | `string` | `""` | 通过[表达式](../../docs/concepts/expression)来配置停止刷新的条件 | | stopAutoRefreshWhenModalIsOpen | `boolean` | `false` | 当有弹框时关闭自动刷新，关闭弹框又恢复 | | syncLocation | `boolean` | `true` | 是否将过滤条件的参数同步到地址栏 | | draggable | `boolean` | `false` | 是否可通过拖拽排序 | | resizable | `boolean` | `true` | 是否可以调整列宽度 | | itemDraggableOn | `boolean` | | 用[表达式](../../docs/concepts/expression)来配置是否可拖拽排序 | | [saveOrderApi](#saveOrderApi) | [API](../../docs/types/api) | | 保存排序的 api。 | | [quickSaveApi](#quickSaveApi) | [API](../../docs/types/api) | | 快速编辑后用来批量保存的 API。 | | [quickSaveItemApi](#quickSaveItemApi) | [API](../../docs/types/api) | | 快速编辑配置成及时保存时使用的 API。 | | bulkActions | Array<[Action](./action)> | | 批量操作列表，配置后，表格可进行选中操作。 | | messages | `Object` | | 覆盖消息提示，如果不指定，将采用 api 返回的 message | | messages.fetchFailed | `string` | | 获取失败时提示 | | messages.saveOrderFailed | `string` | | 保存顺序失败提示 | | messages.saveOrderSuccess | `string` | | 保存顺序成功提示 | | messages.quickSaveFailed | `string` | | 快速保存失败提示 | | messages.quickSaveSuccess | `string` | | 快速保存成功提示 | | primaryField | `string` | `"id"` | 设置 ID 字段名。 | | perPage | `number` | 10 | 设置一页显示多少条数据。 | | orderBy | `string` | | 默认排序字段，这个是传给后端，需要后端接口实现 | | orderDir | `asc` \| `desc` | | 排序方向 | | defaultParams | `Object` | | 设置默认 filter 默认参数，会在查询的时候一起发给后端 | | pageField | `string` | `"page"` | 设置分页页码字段名。 | | perPageField | `string` | `"perPage"` | 设置分页一页显示的多少条数据的字段名。注意：最好与 defaultParams 一起使用，请看下面例子。 | | totalField | `string` | `"total"` | 设置数据返回中用来表示数据总量的字段名 | | pageDirectionField | `string` | `"pageDir"` | 分页方向字段名可能是 forward 或者 backward | | perPageAvailable | `Array` | `[5, 10, 20, 50, 100]` | 设置一页显示多少条数据下拉框可选条数。 | | orderField | `string` | | 设置用来确定位置的字段名，设置后新的顺序将被赋值到该字段中。 | | hideQuickSaveBtn | `boolean` | `false` | 隐藏顶部快速保存提示 | | autoJumpToTopOnPagerChange | `boolean` | `false` | 当切分页的时候，是否自动跳顶部。 | | syncResponse2Query | `boolean` | `true` | 将返回数据同步到过滤器上。 | | keepItemSelectionOnPageChange | `boolean` | `true` | 保留条目选择，默认分页、搜索后，用户选择条目会被清空，开启此选项后会保留用户选择，可以实现跨页面批量操作。 | | labelTpl | `string` | | 单条描述模板，`keepItemSelectionOnPageChange`设置为`true`后会把所有已选择条目列出来，此选项可以用来定制条目展示文案。 | | maxKeepItemSelectionLength | `number` | `true` | 和`keepItemSelectionOnPageChange`搭配使用，限制最大勾选数。 | | maxItemSelectionLength | `number` | `true` | 可单独使用限制当前页的最大勾选数，也可以和`keepItemSelectionOnPageChange`搭配使用达到和 maxKeepItemSelectionLength 一样的效果。 | | headerToolbar | Array | `['bulkActions', 'pagination']` | 顶部工具栏配置 | | footerToolbar | Array | `['statistics', 'pagination']` | 底部工具栏配置 | | alwaysShowPagination | `boolean` | `false` | 是否总是显示分页 | | affixHeader | `boolean` | `true` | 是否固定表头(table 下) | | affixFooter | `boolean` | `false` | 是否固定表格底部工具栏 | | autoGenerateFilter | `Object \| boolean` | | 是否开启查询区域，开启后会根据列元素的 `searchable` 属性值，自动生成查询条件表单 | | resetPageAfterAjaxItemAction | `boolean` | `false` | 单条数据 ajax 操作后是否重置页码为第一页 | | autoFillHeight | `boolean` 丨 `{height: number}` | | 内容区域自适应高度 | | canAccessSuperData | `boolean` | `true` | 指定是否可以自动获取上层的数据并映射到表格行数据上，如果列也配置了该属性，则列的优先级更高 | | matchFunc | `string` | [`CRUDMatchFunc`](#匹配函数) | 自定义匹配函数, 当开启`loadDataOnce`时，会基于该函数计算的匹配结果进行过滤，主要用于处理列字段类型较为复杂或者字段值格式和后端返回不一致的场景 | `3.5.0` | | parsePrimitiveQuery | [`ParsePrimitiveQueryOptions`](#ParsePrimitiveQueryOptions) | `true` | 是否开启 Query 信息转换，开启后将会对 url 中的 Query 进行转换，默认开启，默认仅转化布尔值 | `3.6.0` | 注意除了上面这些属性，CRUD 在不同模式下的属性需要参考各自的文档，比如 - 默认[Table](./table)模式里的[列配置](./table#列配置属表)。 - [Cards](./cards) 模式。 - [List](./list) 模式。 ### 列配置属性表除了 Table 组件默认支持的列配置，CRUD 的列配置还额外支持以下属性： | 属性名 | 类型 | 默认值 | 说明 | 版本 | | ------------------ | ------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------- | ------- | | sortable | `boolean` | `false` | 是否可排序 | | searchable | `boolean` \| `Schema` | `false` | 是否可快速搜索，开启`autoGenerateFilter`后，`searchable`支持配置`Schema` | | filterable | `boolean` \| [`QuickFilterConfig`](./crud#quickfilterconfig) | `false` | 是否可快速搜索，`options`属性为静态选项，支持设置`source`属性从接口获取选项 | | quickEdit | `boolean` \| [`QuickEditConfig`](./crud#quickeditconfig) | - | 快速编辑，一般需要配合`quickSaveApi`接口使用 | | quickEditEnabledOn | `SchemaExpression` | - | 开启快速编辑条件[表达式](../../docs/concepts/expression) | | | textOverflow | `string` | `default` | 文本溢出后展示形式，默认换行处理。可选值 `ellipsis` 溢出隐藏展示， `noWrap` 不换行展示(仅在列为静态文本时生效) | `6.9.0` | #### QuickFilterConfig | 属性名 | 类型 | 默认值 | 说明 | 版本 | | ------------- | ----------------------------------------- | ------- | -------------------------------------------------------- | --------------------------- | | options | `Array` | - | 静态选项 | | | multiple | `boolean` | `false` | 是否支持多选 | | | source | [`Api`](../../docs/types/api) \| `string` | - | 选项 API 接口 | `3.6.0`版本后支持上下文变量 | | refreshOnOpen | `boolean` | `false` | 配置 source 前提下，每次展开筛选浮层是否重新加载选项数据 | `2.9.0` | | strictMode | `boolean` | `false` | 严格模式，开启严格模式后，会采用 JavaScript 严格相等比较 | `2.3.0` | #### QuickEditConfig | 属性名 | 类型 | 默认值 | 说明 | 版本 | | --------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- | ------- | | type | `SchemaType` | - | 表单项组件类型 | | | body | `SchemaCollection` | - | 组件容器，支持多个表单项组件 | | | mode | `'inline' \| 'popOver'` | `'popOver'` | 编辑模式，inline 为行内编辑，popOver 为浮层编辑 | | | icon | `string` | - | 自定义快速编辑按钮的图标 | `6.1.0` | | saveImmediately | `boolean` 或 `{api: Api}` | `false` | 是否修改后即时保存，一般需要配合`quickSaveItemApi`接口使用，也可以直接配置[`Api`](../../docs/types/api) | | | resetOnFailed | `boolean` | - | 接口请求失败时，是否重置数据 | | ### columns-toggler 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------------- | ------------------------------ | --------- | -------------------------------------- | | label | `string` | | 按钮文字 | | tooltip | `string` | | 按钮提示文字 | | disabledTip | `string` | | 按钮禁用状态下的提示 | | align | `"left" \| "right"` | `"left"` | 点击内容是否关闭 | | size | `"xs" \| "sm" \| "md" \| "lg"` | | 按钮大小，参考[按钮](./action) | | footerBtnSize | `"xs" \| "sm" \| "md" \| "lg"` | | 弹窗底部按钮大小，参考[按钮](./action) | | level | `string` | `default` | 按钮样式，参考[按钮](./action) | | draggable | `boolean` | `false` | 是否可通过拖拽排序 | | defaultIsOpened | `boolean` | `false` | 默认是否展开 | | hideExpandIcon | `boolean` | `true` | 是否隐藏展开的图标 | | overlay | `boolean` | `false` | 是否显示遮罩层 | | closeOnOutside | `boolean` | | 点击外部是否关闭 | | closeOnClick | `boolean` | | 点击内容是否关闭 | | iconOnly | `boolean` | `false` | 是否只显示图标。 | | icon | `string` | | 按钮的图标 | | className | `string` | | 外层 CSS 类名 | | btnClassName | `string` | | 按钮的 CSS 类名 | | modalSize | `string` | | 弹窗大小，参考[弹窗](./dialog) | | modalWidth | `string` | | 弹窗宽度 | | modalHeight | `string` | | 弹窗高度 | | modalColumnCount | `number` | | 弹窗内每行显示的列数 | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | fetchInited | `responseData` 接口数据返回
`responseStatus` 接口返回状态
`responseMsg` 响应消息 | 远程初始化数据接口请求完成时触发 | | quickSaveSucc | `result` 接口数据返回
`rows: object[]` 修改了的行集合
`rowsDiff: object[]` 与 rows 不同的地方时，对象中只有修改的部分和主键字段
`indexes: Array` 修改的行索引，如果是树形模式，下标是字符串路劲如 `0.1`
`rowsOrigin: object[]` 原始数据 | 快速编辑完后保存成功触发 | | quickSaveFail | `error` 错误原因 | 快速编辑完后保存失败 | | quickSaveItemSucc | `result` 接口数据返回
`item: object` 当亲修改的那行数据
`modified:object` 质只包含修改的部分
`origin: object` 原始数据 | 快速编辑单条保存成功后触发 | | quickSaveItemFail | `error` 错误原因 | 快速编辑单条保存失败后触发 | | saveOrderSucc | `result` 接口数据返回
`其他` 请参考 [拖拽排序](#拖拽排序) 章节说明 | 拖拽排序保存成功后触发 | | saveOrderFail | `error` 错误原因 | 拖拽排序保存失败后触发 | | selectedChange | `selectedItems: item[]` 已选择行
`selectedIndexes: string[]` 已选择行索引
`unSelectedItems: item[]` 未选择行 | 手动选择表格项时触发 | | columnSort | `orderBy: string` 列排序列名
`orderDir: string` 列排序值 | 点击列排序时触发 | | columnFilter | `filterName: string` 列筛选列名
`filterValue: string \| undefined` 列筛选值 | 点击列筛选时触发，点击重置后事件参数`filterValue`为`undefined` | | columnSearch | `searchName: string` 列搜索列名
`searchValue: object` 列搜索数据 | 点击列搜索时触发 | | orderChange | `movedItems: item[]` 已排序数据 | 手动拖拽行排序时触发 | | columnToggled | `columns: item[]` 当前显示的列配置数据 | 点击自定义列时触发 | | rowClick | `item: object` 行点击数据
`index: number` 行索引
`indexPath: string` 行索引路径 | 点击整行时触发 | | rowDbClick | `item: object` 行点击数据
`index: number` 行索引
`indexPath: string` 行索引路径 | 双击整行时触发 | | rowMouseEnter | `item: object` 行移入数据
`index: number` 行索引
`indexPath: string` 行索引路径 | 移入整行时触发 | | rowMouseLeave | `item: object` 行移出数据
`index: number` 行索引
`indexPath: string` 行索引路径 | 移出整行时触发 | ### selectedChange 在开启批量操作后才会用到，可以尝试勾选列表的行记录。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "selectedChange": { "actions": [ { "actionType": "toast", "args": { "msg": "已选择${event.data.selectedItems.length}条记录" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### columnSort 列排序，可以尝试点击`Browser`列右侧的排序图标。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "columnSort": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "orderBy：${event.data.orderBy},orderDir：${event.data.orderDir}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### columnFilter 列过滤，可以尝试点击`Rendering engine`列右侧的筛选图标。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "columnFilter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "filterName：${event.data.filterName},filterValue：${event.data.filterValue}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### columnSearch 列检索，，可以尝试点击`ID`列右侧的检索图标。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "columnSearch": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "searchName：${event.data.searchName},searchValue：${event.data.searchValue|json}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### columnToggled 点击自定义列，可以尝试修改`自定义列`的配置。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "columnToggled": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "当前显示${event.data.columns.length}列" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### orderChange 在开启拖拽排序行记录后才会用到，排序确认后触发。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "draggable": true, "onEvent": { "orderChange": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "${event.data.movedItems.length}行发生移动" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### rowClick 点击行记录。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "rowClick": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "行单击数据：${event.data.item|json}；行索引：${event.data.index}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### rowDbClick 双击行记录。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "rowDbClick": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "行单击数据：${event.data.item|json}；行索引：${event.data.index}" } } ] } }, "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### rowMouseEnter 鼠标移入行记录。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "rowMouseEnter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "行索引：${event.data.index}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### rowMouseLeave 鼠标移出行记录。 ```schema: scope="body" { "type": "page", "body": { "type": "crud", "api": "/api/mock2/sample", "syncLocation": false, "onEvent": { "rowMouseLeave": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "行索引：${event.data.index}" } } ] } }, "bulkActions": [ { "label": "批量删除", "actionType": "ajax", "api": "delete:/api/mock2/sample/${ids|raw}", "confirmText": "确定要批量删除?" } ], "columns": [ { "name": "id", "label": "ID", "searchable": true }, { "name": "engine", "label": "Rendering engine", "filterable": { "options": [ "Internet Explorer 4.0", "Internet Explorer 5.0" ] } }, { "name": "browser", "label": "Browser", "sortable": true }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } } ``` ### 列的事件表表格的默认列定义的事件如下，即 click、mouseenter、mouseleave。如果列定义是其他组件，则事件表就是这个组件对应的事件表，例如列定义是 Switch 组件，则可以监听 [Switch 的 change 事件](./form/switch#%E4%BA%8B%E4%BB%B6%E8%A1%A8)。 | 事件名称 | 事件参数 | 说明 | | ---------- | ----------------------------------- | ---------------------------------------------- | | click | `[columnName]: string` 对应列名的值 | 监听表格列点击事件，表格数据点击时触发 | | mouseenter | `[columnName]: string` 对应列名的值 | 监听表格列鼠标移入事件，表格数据鼠标移入时触发 | | mouseleave | `[columnName]: string` 对应列名的值 | 监听表格列鼠标移出事件，表格数据鼠标移出时触发 | ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | --------------- | --------------------- | -------------------------- | | reload | - | 刷新列表请求 | | setValue | `value: object` | 更新列表记录 | | select | 转 table 组件动作说明 | 设置选中项 | | selectAll | 转 table 组件动作说明 | 设置表格全部项选中 | | clearAll | 转 table 组件动作说明 | 清空表格所有选中项 | | initDrag | 转 table 组件动作说明 | 开启表格拖拽排序功能 | | cancelDrag | 转 table 组件动作说明 | 取消表格拖拽排序功能 | | submitQuickEdit | 转 table 组件动作说明 | 快速编辑数据提交 | | toggleExpanded | 转 table 组件动作说明 | 切换某行数据是展开还是收起 | | setExpanded | 转 table 组件动作说明 | 展开或收起某行数据 | value 结构说明： | 属性名 | 类型 | 默认值 | 说明 | | -------------- | -------- | ------ | -------- | | items 或 rows | `item[]` | | 列表记录 | | count 或 total | `number` | | 记录总数 | ### 初始选中行利用 `fetchInited` 事件和 `select` 动作可以完成初始选中行。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### reload #### 只做刷新重新发送`api`请求，刷新 CRUD 时，只配置`componentId`目标组件 ID 即可。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 追加请求参数并刷新刷新 CRUD 时，如果配置了`data`，将先发送`data`给目标 CRUD 组件，并将该数据合并到目标 CRUD 组件的数据域中，然后重启请求数据，并且自动追加`data`参数到请求中。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 通过`&: $$`追加触发事件的按钮所在数据域的所有数据，即`name、age、date`。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 局部刷新（仅刷新指定行） > `6.3.0`及以上版本需要搭配 `deferApi` 属性使用，同时刷新动作指定 `args.index` 或者 `args.condition` 来指定刷新哪一行。 ```schema { "type": "page", "data": { "name": "amis", "age": 18, "date": "2023-6-6" }, "body": [ { "type": "button", "label": "刷新 id 为 2 的行", level: 'primary', "className": "mb-2", "onEvent": { "click": { "actions": [ { "componentId": "crud_reload1", "actionType": "reload", "args": { "condition": "${id == 2}" } }, { "componentId": "crud_reload1", "actionType": "setExpanded", "args": { "condition": "${id == 2}", "value": true } } ] } } }, { "type": "crud", "api": "/api/mock2/crud/table6", "deferApi": "/api/mock2/crud/table6?parentId=${id}&waitSeconds=2", "id": "crud_reload1", "syncLocation": false, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" } ] } ] } ``` ### toggleExpanded > `6.3.0`及以上版本切换展开状态。通过指定 `args.index` 或者 `args.condition` 来指定切换哪一行。参考局部刷新里面的示例。 ### setExpanded > `6.3.0`及以上版本设置展开状态。通过指定 `args.index` 或者 `args.condition` 来指定切换哪一行，通过 `args.value` 来设置是展开还是收起。参考局部刷新里面的示例。 ### setValue 通过`setValue`更新指定 CRUD 的数据。 #### 合并数据默认`setValue`会将新数据与目标组件数据进行合并。 ```schema: scope="body" [ { "type": "button", "label": "更新数据，记录总数被更新为20", "onEvent": { "click": { "actions": [ { "actionType": "setValue", "componentId": "crud_setvalue", "args": { "value": { "count": 20 } } } ] } } }, { "type": "crud", "id": "crud_setvalue", "syncLocation": false, "api": "/api/mock2/sample", "quickSaveApi": "/api/mock2/sample/bulkUpdate", "headerToolbar": [ { "type": "tpl", "tpl": "记录总数：${count}" } ], "columns": [ { "name": "id", "label": "ID", "id": "u:3db3f2b1b99e" }, { "name": "engine", "label": "engine", "id": "u:0b9be99f3403" }, { "name": "version", "label": "version", "id": "u:4868d7db0139" } ] } ] ``` #### 覆盖数据可以通过`"dataMergeMode": "override"`来覆盖目标组件数据。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 更新列表记录 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 更新指定行记录可以通过指定`index`或者`condition`来分别更新指定索引的行记录和指定满足条件（条件表达式或者 ConditionBuilder）的行记录，另外`replace`同样生效，即可以完全替换指定行记录，也可以对指定行记录做合并。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 提交数据更改通过表达式或者行号更新数据后，并不会提交到后端，需要添加 `submitQuickEdit` 动作来提交。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 行记录中字段赋值需要通过表达式配置动态`id`和`componentId`。例如修改`engine`选中状态的同时选中`version`，勾选`id`的同时去掉对`engine`的选中。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Zh CN Components Custom (`docs/zh-CN/components/custom.md`) --- title: Custom 自定义组件 description: type: 0 group: ⚙ 组件 menuName: Custom 自定义组件 icon: order: 26 --- 用于实现自定义组件，它解决了之前 JS SDK 和可视化编辑器中难以支持自定义组件的问题。 ## 基本用法设置 type 类型为 custom ### onMount 这是节点在初始化的时候执行的函数，它接收三个参数： - dom，组件加载之后的 dom 节点 - data，组件初始值，需要设置 name - onChange，修改这个组件对应 name 的值 - props，后面会单独介绍比如在这样的 form 组件中： ```javascript { type: 'page', title: '表单页面', body: { type: 'form', title: 'custom 组件', body: [ { type: 'custom', name: 'myName', label: '自定义组件', onMount: (dom, value, onChange, props) => { const button = document.createElement('button'); button.innerText = '点击修改'; button.onclick = event => { // 这个 onChange 方法只有放在表单项中才能调用，第二个参数是表单项名称 onChange('new', 'myName'); event.preventDefault(); }; dom.appendChild(button); } } ] } } ``` 点击按钮之后，执行 `onChange` 函数，就会将 `myName` 这个参数的值改成 `new`，点击表单提交的时候，就会有一个 `myName=new` 的表单数据。 ### onUpdate onUpdate 是在数据变更的时候调用，注意这个数据变更会包含表单内的所有其他组件。 ```javascript { type: 'page', title: '表单页面', body: { type: 'form', title: 'custom 组件', body: [ { name: 'email', label: '邮箱', type: 'input-text' }, { name: 'username', label: '用户名', type: 'input-text' }, { type: 'custom', label: '自定义组件', onUpdate: (dom, data, prevData, props) => { console.log('data', data, prevData) } } ] } } ``` 这个例子中，无论是邮箱还是用户名修改，都会触发 onUpdata 函数，其中 `data` 是当前值，`prevData` 是之前的值： 1. 如果修改 email，则 data 将会是 `{email: 'xxx'}`，prevData 是 `{}` 2. 如果再次修改 email，则 data 将会是 `{email: 'xxx1'}`，prevData 是 `{email: 'xxx '}` 3. 如果修改 username，则 data 将会是 `{email: 'xxx1', username: 'yyy'}`，prevData 是 `{email: 'xxx1'}` ### onUnmount onUnmount 是在组件销毁的时候执行，可以在这里做资源清理，这个函数只有一个 props 参数。 ### Vue.js 因为 onMount 拿到的 dom 就是标准的 dom，所以可以执行任意 JavaScript 代码，包括 jQuery 等，下面的例子演示了如何使用 vue 2.0 实现自定义组件： ```javascript { type: 'page', title: '表单页面', body: { type: 'form', title: 'custom 组件', body: [ { type: 'custom', name: 'my-custom', html: `

{{ todo.text }}

`, label: '自定义组件', onMount: (dom, data, onChange, props) => { const app = new Vue({ el: dom, data: { todos: [ { text: 'hello' }, { text: 'world' }, { text: 'vue' } ] } }) } } ] } } ``` 【温馨提示】 custom 组件中使用 vue2 语法，请先引入vue.js（umd 或 global 模块，比如：https://cdn.jsdelivr.net/npm/vue@2.7.14/dist/vue.js）。同理，使用 vue3 语法请先引入 vue3 对应的 umd 或 global 模块，比如：https://unpkg.com/vue@3/dist/vue.global.js 。 ### props 前面可以看到所有函数最后都有一个 props 参数，在这个参数里能拿到 amis 内部属性和方法，比如弹框 ```javascript onMount: (dom, data, onChange, props) => { const button = document.createElement('button'); button.innerText = '点击修改姓名'; button.onclick = event => { onChange('new name', 'name'); props.onAction( event, { type: 'action', label: '弹个框', actionType: 'dialog', dialog: { title: '弹框', body: 'Hello World!' } }, {} // 这是 data ); event.preventDefault(); }; dom.appendChild(button); }; ``` 或者执行 `props.env.notify('success', '执行成功')` 来在右上角弹出提示等。 ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------- | --------- | -------- | --------------------------------------------- | | type | 'custom' | | | | id | `string` | | 节点 id | | name | `string` | | 节点名称 | | className | `string` | | 节点 class | | inline | `boolean` | false | 默认使用 div 标签，如果 true 就使用 span 标签 | | html | `string` | | 初始化节点 html | | onMount | `string` | Function | 节点初始化之后调的用函数 | | onUpdate | `string` | Function | 数据有更新的时候调用的函数 | | onUnmount | `string` | Function | 节点销毁的时候调用的函数 | --- ### Zh CN Components Date (`docs/zh-CN/components/date.md`) --- title: Date 日期时间 description: type: 0 group: ⚙ 组件 menuName: Date icon: order: 39 --- 用于展示日期 ## 基本使用 ```schema { "type": "page", "body": { "type": "date", "value": "1591326307" } } ``` ## 用作 Field 时当用在 Table 的列配置 Column、List 的内容、Card 卡片的内容和表单的 Static-XXX 中时，可以设置`name`属性，映射同名变量 ### Table 中的列类型 ```schema: scope="body" { "type": "table", "data": { "items": [ { "id": "1", "date": "1591326307" }, { "id": "2", "date": "1591321307" }, { "id": "3", "date": "1591322307" } ] }, "columns": [ { "name": "id", "label": "Id" }, { "name": "date", "label": "日期", "type": "date" } ] } ``` List 的内容、Card 卡片的内容配置同上 ### Form 中静态展示 ```schema: scope="body" { "type": "form", "data": { "now": "1591322307" }, "body": [ { "type": "static-date", "name": "now", "label": "日期", "format": "YYYY年MM月DD日 HH时mm分ss秒" } ] } ``` ## 配置展示格式例如你想将某一个时间值，以 `xxxx年xx月xx日 xx时xx分xx秒` 这样的格式输出，那么查找 [moment 文档](https://momentjs.com/docs/#/displaying/format/) 可知配置格式应为 `YYYY年MM月DD日 HH时mm分ss秒`，即： ```schema { "type": "page", "data": { "now": 1586865590 }, "body": { "type": "date", "value": "1586865590", "format": "YYYY年MM月DD日 HH时mm分ss秒" } } ``` ## 配置数据格式如果你的数据值默认不是`X`格式（时间戳秒格式），那么需要配置 `valueFormat` 参数用于解析当前时间值，比如毫秒是配置 `"valueFormat": "x"`。除此之外还支持各种自定义日期格式，例如下面`value`值为：`"2020/4/14 19:59:50"`，查阅 [moment 文档](https://momentjs.com/docs/#/displaying/format/) 可知，需要配置数据格式为 `"YYYY/MM/DD HH:mm:ss"`，然后我们配置输出格式`format`，输出指定格式日期： ```schema { "type": "page", "body": { "type": "date", "value": "2020/4/14 19:59:50", "valueFormat": "YYYY/MM/DD HH:mm:ss", "format": "YYYY年MM月DD日 HH时mm分ss秒" } } ``` ## 转成相对当前时间的描述 ```schema { "type": "page", "body": { "type": "date", "fromNow": true, "value": "1591326307" } } ``` ## 设置展示时区通过配置 `displayTimeZone` 参数，可以设置展示时区，默认展示当前时区。 ```schema: scope="body" { "type": "crud", "api": { "method": "get", "url": "/whatever/api", "mockResponse": { "status": 200, "data": [ { "date": "2023-10-27 15:00:00" } ] } }, "columns": [ { "type": "date", "label": "Asia/Shanghai", "name": "date", "displayTimeZone": "Asia/Shanghai", "format": "YYYY-MM-DD HH:mm:ss" }, { "type": "date", "label": "America/Los_Angeles", "name": "date", "displayTimeZone": "America/Los_Angeles", "format": "YYYY-MM-DD HH:mm:ss" }, { "type": "date", "name": "date", "label": "Asia/Tokyo", "displayTimeZone": "Asia/Tokyo", "format": "YYYY-MM-DD HH:mm:ss" } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | --------------- | --------- | ------------ | ------------------------------------------------------------------------------------------------------ | ----------------------- | | type | `string` | | 如果在 Table、Card 和 List 中，为`"date"`；在 Form 中用作静态展示，为`"static-date"` | | className | `string` | | 外层 CSS 类名 | | value | `string` | | 显示的日期数值 | | name | `string` | | 在其他组件中，时，用作变量映射 | | placeholder | `string` | `-` | 占位内容 | | displayFormat | `string` | `YYYY-MM-DD` | 展示格式, 更多格式类型请参考 [文档](https://momentjs.com/docs/#/displaying/format/) | 版本号 3.4.0 及以上支持 | | valueFormat | `string` | `X` | 数据格式，默认为时间戳。更多格式类型请参考 [文档](https://momentjs.com/docs/#/displaying/format/) | | fromNow | `boolean` | `false` | 是否显示相对当前的时间描述，比如: 11 小时前、3 天前、1 年前等，fromNow 为 true 时，format 不生效。 | | updateFrequency | `number` | `60000` | 更新频率，默认为 1 分钟 | | displayTimeZone | `string` | | 设置日期展示时区，可设置清单参考：https://gist.github.com/diogocapela/12c6617fc87607d11fd62d2a4f42b02a | --- ### Zh CN Components Dialog (`docs/zh-CN/components/dialog.md`) --- title: Dialog 对话框 description: type: 0 group: ⚙ 组件 menuName: Dialog 对话框 icon: order: 41 --- Dialog 弹框主要由 [Action](./action) 触发，主要展示一个对话框以供用户操作。 ## 基本用法 ```schema: scope="body" { "label": "点击弹框", "type": "button", "actionType": "dialog", "dialog": { "title": "弹框标题", "body": "这是一个弹框" } } ``` ## 配置尺寸 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "较小的弹框", "actionType": "dialog", "dialog": { "size": "sm", "title": "提示", "body": "这是个简单的弹框" } }, { "type": "button", "label": "标准弹框", "actionType": "dialog", "dialog": { "title": "提示", "body": "这是个简单的弹框" } }, { "type": "button", "label": "较大的弹框", "actionType": "dialog", "dialog": { "size": "lg", "title": "提示", "body": "这是个简单的弹框" } }, { "type": "button", "label": "很大的弹框", "actionType": "dialog", "dialog": { "size": "xl", "title": "提示", "body": "这是个简单的弹框" } }, { "type": "button", "label": "占满屏幕的弹框", "actionType": "dialog", "dialog": { "size": "full", "title": "全屏弹框", "body": "弹框尽可能占满，内容部分滚动。" } } ] } ``` ## 弹框与数据映射默认弹框内由于数据链的存在，会自动映射父级同名变量，例如下例： ```schema: scope="body" { "type": "crud", "api": "/api/mock2/sample", "draggable": true, "columns": [ { "name": "id", "label": "ID" }, { "name": "engine", "label": "Rendering engine" }, { "name": "browser", "label": "Browser" }, { "name": "platform", "label": "Platform(s)" }, { "name": "version", "label": "Engine version" }, { "name": "grade", "label": "CSS grade" }, { "type": "button", "label": "一个弹框", "actionType": "dialog", "dialog": { "title": "一个弹框", "body": [ { "type": "form", "api": "/api/mock2/sample/$id", "body": [ { "type": "input-text", "name": "engine", "label": "Engine" } ] } ] } } ] } ``` 上例弹框中的表单项 `Engine` 会自动映射到父级数据中的 `engine` 变量，如果想调整当前特性，如你想调整父级映射变量的字段，可以利用[数据映射](../../docs/concepts/data-mapping)，例如： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 上例给 `dialog` 中配置 `data` 属性，可以将上层的 `engine` 变量映射为 `engine2`。请注意点击“新增”按钮后 dialog 内 form 的数据域会直接继承 CRUD 所在的数据域，如果 CRUD 过滤器中查询字段和 dialog 表单中的字段相同时，会错误的将外部数据映射到表单数据域内，需要配置数据映射将相关字段绑定的数据删除`{"&": "$$", "status": "__undefined"}` ## 多级弹框 ```schema: scope="body" { "type": "button", "label": "多级弹框", "actionType": "dialog", "dialog": { "title": "提示", "body": "这是个简单的弹框", "actions": [ { "type": "button", "actionType": "confirm", "label": "确认", "primary": true }, { "type": "button", "actionType": "dialog", "label": "再弹一个", "dialog": { "title": "弹框中的弹框", "body": "如果你想，可以无限弹下去", "actions": [ { "type": "button", "actionType": "dialog", "label": "来吧", "level": "info", "dialog": { "title": "弹框中的弹框", "body": "如果你想，可以无限弹下去", "actions": [ { "type": "button", "actionType": "confirm", "label": "不弹了", "primary": true } ] } } ] } } ] } } ``` ## 动作后关闭弹框在弹框中配置行为按钮，可以在按钮上配置`"close": true`，在行为完成后，关闭当前弹框。 ```schema: scope="body" { "type": "button", "label": "弹个框", "actionType": "dialog", "dialog": { "title": "弹框", "body": [ { "type": "button", "label": "默认的 ajax 请求", "actionType": "ajax", "api": "/api/mock2/form/saveForm?waitSeconds=1" }, { "type": "button", "label": "ajax 请求成功后关闭弹框", "actionType": "ajax", "api": "/api/mock2/form/saveForm?waitSeconds=1", "close": true } ] } } ``` 以上例子是关闭当前弹窗，如果希望关闭上层弹窗，则需要给目标弹窗设置 `name` 属性，然后配置按钮 `close` 属性为目标 `name` 属性如： ```schema: scope="body" { "type": "button", "label": "多级弹框", "actionType": "dialog", "dialog": { "title": "提示", "body": "这是个简单的弹框", "name": "dialog_1", "actions": [ { "type": "button", "actionType": "confirm", "label": "确认", "primary": true }, { "type": "button", "actionType": "dialog", "label": "再弹一个", "dialog": { "title": "弹框中的弹框", "body": "关闭当前弹窗的时候把外层的弹窗一起关了", "actions": [ { "type": "button", "label": "关闭所有", "level": "info", "close": "dialog_1" } ] } } ] } } ``` ## 配置弹窗的按钮默认弹窗会自动生成两个按钮，一个取消，一个确认。如果通过 `actions` 来自定义配置，则以配置的为准。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "无按钮", "actionType": "dialog", "dialog": { "title": "提示", "actions": [], "body": "无按钮的弹框" } }, { "type": "button", "label": "只有一个确认按钮", "actionType": "dialog", "dialog": { "title": "提示", "actions": [{ "type": "button", "actionType": "confirm", "label": "OK", "primary": true }], "body": "只有一个 OK 的弹框" } } ] } ``` ## 弹框中配置表单 ### 基本使用 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "dialog", "dialog": { "title": "在弹框中的表单", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "username", "required": true, "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } } } ``` ### 提交表单或 ajax 请求弹框中通过配置`form`或`ajax`行为按钮，可以实现`form`提交和`ajax`请求操作。 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "dialog", "dialog": { "title": "在弹框中的表单", "actions": [ { "label": "提交表单", "actionType": "submit", "primary": true, "type": "button" }, { "label": "ajax请求", "actionType": "ajax", "primary": true, "type": "button", "api": "/api/mock2/form/saveForm?waitSeconds=2" } ], "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "text", "required": true, "label": "用户名", "placeholder": "请输入用户名" }, { "type": "input-password", "name": "password", "label": "密码", "placeholder": "请输入密码", "required": true }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } } } ``` ### 提交表单或 ajax 请求后不关闭弹框默认情况下，当弹框中配置了 form 并进行了**提交表单操作（confirm）**或进行了**`ajax`请求**，请求成功后，会自动关闭当前弹框，你可以通过手动设置`"close": false` 来禁止该默认特性。 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "dialog", "dialog": { "title": "在弹框中的表单", "actions": [ { "label": "提交表单后不关闭", "actionType": "submit", "close": false, "primary": true, "type": "button" }, { "label": "ajax请求后不关闭", "actionType": "ajax", "primary": true, "type": "button", "api": "/api/mock2/form/saveForm?waitSeconds=2" } ], "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "text", "required": true, "label": "用户名", "placeholder": "请输入用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] } } } ``` ## feedback 反馈弹框 feedback 反馈弹框是指，在 ajax 请求后，可以显示一个弹框，进行反馈操作 ### feedback 基本使用 ```schema: scope="body" { "type": "button", "label": "Feedback", "actionType": "ajax", "api": "/api/mock2/form/initData?waitSeconds=2", "tooltip": "点击我后会发送一个请求，请求回来后，弹出一个框。", "feedback": { "title": "操作成功", "body": "xxx 已操作成功" } } ``` ### 弹框中配置 feedback #### 关闭 feedback 弹框时，同时关闭上层弹框当你在弹框中配置了 feedback，操作之后，你希望关闭当前 feedback 弹框同时，关闭上层的弹框，具体有两种方式 ##### 1. 不请求接口，直接关闭 `feedback`的`actions`中配置 `"actionType": "close"` 的按钮 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ##### 2. 请求接口，请求成功后，关闭所有弹框需要在 feedback 的 `body` 中添加 Form 组件，并配置`"actionType": "confirm"`， ``` /* Detailed source-code truncated for AI context efficiency. */ ``` > 注意上面的例子：如果你的触发`feedback`的按钮`actionType`为`ajax`时，为需要额外在按钮上配置`"close": true` #### 取消 feedback 弹框时，不同时关闭上层弹框该场景只适用于**不请求接口关闭弹框**的场景，需要在 feedback 层添加`"skipRestOnCancel": true` ```schema: scope="body" { "type": "button", "label": "弹一个框", "actionType": "dialog", "dialog": { "title": "提示", "body": { "type": "form", "api": "/api/mock2/form/initData?waitSeconds=1", "body": [ { "type": "tpl", "tpl": "这是一个简单的弹框" } ] }, "actions": [ { "type": "button", "actionType": "confirm", "label": "Feedback", "feedback": { "body": "这是一个feedback弹框", "skipRestOnCancel": true, "actions": [ { "type": "button", "actionType": "close", "label": "关闭" } ] } } ] } } ``` #### 确认 feedback 弹框时，不同时关闭上层弹框如果想让 feedback 弹框确认后，让之前触发这个 feedback 的按钮中断，那么需要配置 `skipRestOnConfirm`，这就意味着之前触发这个 feedback 的按钮必须重新提交一次。 ### 根据条件显示 feedback 可以根据条件弹出，例如下面这个例子，只有当接口返回的时间戳可以整除 2 时才显示弹框。 ```schema: scope="body" { "type": "button", "label": "条件feedback", "actionType": "ajax", "api": "/api/mock2/form/initData?waitSeconds=1", "feedback": { "visibleOn": "!(this.date % 2)", "title": "操作成功", "body": "当前时间戳: ${date}" } } ``` ## 配置 Esc 键和点击外部关闭弹框可以通过配置 `closeOnEsc` 和 `closeOnOutside` 支持用 esc 键和点击其它区域关闭弹框。 ```schema: scope="body" { "label": "点击弹框", "type": "button", "actionType": "dialog", "dialog": { "closeOnEsc": true, "closeOnOutside": true, "title": "弹框标题", "body": [ { "type": "input-text", "label": "更复杂的标签提示", "labelRemark": { "trigger": ["click"], "type": "remark", "title": "提示", "content": "

first \nsecond\n${text1}

" }, "name": "text3" }, { "label": "点击弹框2", "type": "button", "actionType": "dialog", "dialog": { "closeOnEsc": true, "closeOnOutside": true, "title": "弹框标题2", "body": "内容" } } ] } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------------- | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------ | | type | `string` | | `"dialog"` 指定为 Dialog 渲染器 | | title | [SchemaNode](../../docs/types/schemanode) | | 弹出层标题 | | body | [SchemaNode](../../docs/types/schemanode) | | 往 Dialog 内容区加内容 | | size | `string` | | 指定 dialog 大小，支持: `xs`、`sm`、`md`、`lg`、`xl`、`full`、`custom` | | width | `number \| string` | | Dialog 宽度, size 为 `custom` 时生效 | | height | `number \| string` | | Dialog 高度, size 为 `custom` 时生效 | | bodyClassName | `string` | `modal-body` | Dialog body 区域的样式类名 | | closeOnEsc | `boolean` | `false` | 是否支持按 `Esc` 关闭 Dialog | | showCloseButton | `boolean` | `true` | 是否显示右上角的关闭按钮 | | showErrorMsg | `boolean` | `true` | 是否在弹框左下角显示报错信息 | | showLoading | `boolean` | `true` | 是否在弹框左下角显示 loading 动画 | | disabled | `boolean` | `false` | 如果设置此属性，则该 Dialog 只读没有提交操作。 | | draggable | `boolean` | | 是否支持拖拽 Dialog | | actions | Array<[Action](./action)> | 【确认】和【取消】 | 如果想不显示底部按钮，可以配置：`[]` | | data | `object` | | 支持[数据映射](../../docs/concepts/data-mapping)，如果不设定将默认将触发按钮的上下文中继承数据。 | | | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 > `[name]`为当前数据域中的字段名，例如：当前数据域为 {username: 'amis'}，则可以通过${username}获取对应的值。 | 事件名称 | 事件参数 | 说明 | | -------- | ------------------------------------------------------------------------ | ------------------ | | confirm | `event.data: object` 弹窗数据
`[name]: any` 当前数据域中指定字段的值 | 点击确认提交时触发 | | cancel | `event.data: object` 弹窗数据
`[name]: any` 当前数据域中指定字段的值 | 点击取消时触发 | ### confirm ```schema: scope="body" [ { "label": "弹个框", "type": "button", "onEvent": { "click": { "actions": [ { "actionType": "dialog", "dialog": { "title": "一个弹框", "body": [ { "type": "alert", "body": "试试点击确认按钮", "level": "info", "className": "mb-1" }, { "type": "form", "title": "表单", "debug": true, "body": [ { "label": "你的名字", "type": "input-text", "name": "name", "id": "u:00ef9e3fe9db", "mode": "horizontal", "size": "md", "value": "Amis" } ], "id": "u:f4b2a90b685b" } ], "onEvent": { "confirm": { "actions": [ { "actionType": "toast", "args": { "msg": "你的名字是${name}" } } ] } } } } ] } } } ] ``` ### cancel ```schema: scope="body" [ { "label": "弹个框", "type": "button", "onEvent": { "click": { "actions": [ { "actionType": "dialog", "dialog": { "title": "一个弹窗", "body": "试试点击取消按钮或者右上角的关闭", "onEvent": { "cancel": { "actions": [ { "actionType": "toast", "args": { "msg": "cancel" } } ] } } } } ] } } } ] ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定`actionType: 动作名称`、`componentId: 该组件id`来触发这些动作，动作配置可以通过`args: {动作配置项名称: xxx}`来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | -------- | -------------------------- | ------------ | | confirm | - | 确认（提交） | | cancel | - | 取消（关闭） | | setValue | `value: object` 更新的数据 | 更新数据 | ### confirm 动作 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "dialog", "dialog": { "title": "在弹框中的表单", "id": "dialog_confirm", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "username", "required": true, "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] }, "actions": [ { "type": "button", "label": "触发确认", "onEvent": { "click": { "actions": [ { "actionType": "confirm", "componentId": "dialog_confirm" } ] } } } ] } } ``` ### cancel 动作 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "dialog", "dialog": { "title": "在弹框中的表单", "id": "dialog_cancel", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "username", "required": true, "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] }, "actions": [ { "type": "button", "label": "触发取消", "onEvent": { "click": { "actions": [ { "actionType": "cancel", "componentId": "dialog_cancel" } ] } } } ] } } ``` ### setValue 动作通过`setValue`更新指定弹窗的数据。 #### 合并数据默认`setValue`会将新数据与目标组件数据进行合并。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 覆盖数据可以通过`"dataMergeMode": "override"`来覆盖目标组件数据。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Zh CN Components Divider (`docs/zh-CN/components/divider.md`) --- title: Divider 分割线 description: type: 0 group: ⚙ 组件 menuName: Divider 分割线 icon: order: 42 --- ## 基本用法 ```schema: scope="body" { "type": "divider" } ``` ## 不同样式 ```schema: scope="body" [ { "type": "divider", "lineStyle": "solid" }, { "type": "divider", "lineStyle": "dashed" } ] ``` ## 带标题的分割线 > `3.5.0`及以上版本 ```schema: scope="body" [ { "type": "divider", "title": "Text", "titlePosition": "left" }, { "type": "divider", "title": "Text", "titlePosition": "center" }, { "type": "divider", "title": "Text", "titlePosition": "right" } ] ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | 版本 | | --------- | -------- | ------------ | --------------------------------------- |---------- | | type | `string` | | `"divider"` 指定为分割线渲染器 | | className | `string` | | 外层 Dom 的类名 | | lineStyle | `string` | `solid` | 分割线的样式，支持`dashed`和`solid` | | direction | `string` | `horizontal` | 分割线的方向，支持`horizontal`和`vertical` | `3.5.0` | | color | `string` | | 分割线的颜色 | `3.5.0` | | rotate | `number` | | 分割线的旋转角度 | `3.5.0` | | title | [SchemaNode](../../docs/types/schemanode) | | 分割线的标题 | `3.5.0` | | titleClassName | `string` | | 分割线的标题类名 | `3.5.0` | | titlePosition | `string` | `center`| 分割线的标题位置，支持`left`、`center`和`right` | `3.5.0` | --- ### Zh CN Components Drawer (`docs/zh-CN/components/drawer.md`) --- title: Drawer 抽屉 description: type: 0 group: ⚙ 组件 menuName: Drawer 抽屉 icon: order: 43 --- ## 基本用法 ```schema: scope="body" { "label": "弹出", "type": "button", "actionType": "drawer", "drawer": { "title": "抽屉标题", "body": "这是一个抽屉" } } ``` ## 多级弹框可以嵌套使用。 ```schema: scope="body" { "type": "button", "label": "多级抽屉", "actionType": "drawer", "drawer": { "title": "提示", "body": "这是个简单的抽屉", "actions": [ { "type": "button", "actionType": "confirm", "label": "确认", "primary": true }, { "type": "button", "actionType": "drawer", "label": "再弹一个", "drawer": { "title": "抽屉中的抽屉", "body": "如果你想，可以继续弹下去", "actions": [ { "type": "button", "actionType": "drawer", "label": "来吧", "level": "info", "drawer": { "title": "抽屉中的抽屉", "body": "如果你想，可以无限弹下去", "actions": [ { "type": "button", "actionType": "confirm", "label": "不弹了", "primary": true } ] } } ] } } ] } } ``` ## 指定弹出方向通过配置 `position`，可以指定抽屉弹出的方向，可选 `left`、`right`、`top` 和 `bottom`。默认为 `right`。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "左侧弹出", "actionType": "drawer", "drawer": { "position": "left", "title": "提示", "body": "这是一个从左侧弹出的抽屉" } }, { "type": "button", "label": "右侧弹出", "actionType": "drawer", "drawer": { "position": "right", "title": "提示", "body": "这是一个从右侧弹出的抽屉" } }, { "type": "button", "label": "顶部弹出", "actionType": "drawer", "drawer": { "position": "top", "title": "提示", "body": "这是一个从顶部弹出的抽屉" } }, { "type": "button", "label": "底部弹出", "actionType": "drawer", "drawer": { "position": "bottom", "title": "提示", "body": "这是一个从底部弹出的抽屉" } } ] } ``` ## 抽屉尺寸通过设置 `size` 来控制抽屉的大小，可选值：`xs`、`sm`、`md`、`lg` 和 `xl`。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "极小框", "actionType": "drawer", "drawer": { "size": "xs", "title": "提示", "body": "这是一个极小的抽屉" } }, { "type": "button", "label": "小框", "actionType": "drawer", "drawer": { "size": "sm", "title": "提示", "body": "这是一个小抽屉" } }, { "type": "button", "label": "中框", "actionType": "drawer", "drawer": { "size": "md", "title": "提示", "body": "这是一个标准的抽屉" } }, { "type": "button", "label": "大框", "actionType": "drawer", "drawer": { "size": "lg", "title": "提示", "body": "这是一个大抽屉" } }, { "type": "button", "label": "超大框", "actionType": "drawer", "drawer": { "size": "xl", "title": "提示", "body": "这是一个超大的抽屉" } }, ] } ``` ## 自定义抽屉尺寸通过设置 `width`（`position` 为 `left` 或 `right` 时生效）和 `height`（`position` 为 `top` 或 `bottom` 时生效）来控制抽屉的尺寸。值如果是数字类型，单位默认使用 `px`, 如果是字符串类型，可以使用自定义 css 宽度变量，如：`%`、`vw`、`px` 等。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "自定义宽度", "actionType": "drawer", "drawer": { "position": "right", "width": 300, "title": "提示", "body": "这是一个自定义 300px 宽度的抽屉" } }, { "type": "button", "label": "自定义高度", "actionType": "drawer", "drawer": { "position": "bottom", "height": 300, "title": "提示", "body": "这是一个自定义 300px 高度的抽屉" } } ] } ``` ## 可拖拽抽屉大小配置 `"resizable": true`，可以拖拽调整 `drawer` 大小。 ```schema: scope="body" { "type": "button", "label": "可拖拽调整大小", "actionType": "drawer", "drawer": { "resizable": true, "title": "提示", "body": "这是一个可拖拽的抽屉" } } ``` ## 是否展示关闭按钮配置 `"showCloseButton": false`，可以隐藏关闭按钮。 ```schema: scope="body" { "type": "button", "label": "无关闭按钮", "actionType": "drawer", "drawer": { "title": "提示", "body": "这是一个没有关闭按钮的抽屉", "showCloseButton": false } } ``` ## 蒙层显示通过配置 `overlay`，来控制是否显示蒙层。默认为 `true`。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "默认", "actionType": "drawer", "drawer": { "overlay": true, "title": "提示", "body": "这是一个有蒙层的抽屉" } }, { "type": "button", "label": "不显示", "actionType": "drawer", "drawer": { "overlay": false, "title": "提示", "body": "这是一个没有蒙层的抽屉" } } ] } ``` ## 关闭方式通过配置 `closeOnOutside`，即可在点击抽屉外部时，直接关闭抽屉。同时可以配置 `closeOnEsc`，让抽屉支持 Esc 键关闭。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "点击抽屉外自动关闭（有蒙层）", "actionType": "drawer", "drawer": { "closeOnOutside": true, "title": "提示", "body": "这是一个简单的抽屉" } }, { "type": "button", "label": "点击抽屉外自动关闭（无蒙层）", "actionType": "drawer", "drawer": { "overlay": false, "closeOnOutside": true, "title": "提示", "body": "这是一个简单的抽屉" } }, { "type": "button", "label": "按键关闭", "actionType": "drawer", "drawer": { "closeOnEsc": true, "title": "提示", "body": "试试按下 Esc" } } ] } ``` ## 动作后关闭抽屉在抽屉中配置行为按钮，可以在按钮上配置 `"close": true`，在行为完成后，关闭当前抽屉。 ```schema: scope="body" { "type": "button", "label": "打开", "actionType": "drawer", "drawer": { "title": "提示", "body": [ { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "默认的 ajax 请求", "actionType": "ajax", "api": "/api/mock2/form/saveForm?waitSeconds=1" }, { "type": "button", "label": "ajax 请求成功后关闭抽屉", "actionType": "ajax", "api": "/api/mock2/form/saveForm?waitSeconds=1", "close": true } ] } ] } } ``` 以上例子是关闭当前抽屉，如果希望关闭上层抽屉，则需要给目标抽屉设置 `name` 属性，然后配置按钮 `close` 属性为目标 `name` 属性如： ```schema: scope="body" { "type": "button", "label": "多级抽屉", "actionType": "drawer", "drawer": { "title": "提示", "body": "这是个简单的抽屉", "name": "drawer_1", "actions": [ { "type": "button", "actionType": "confirm", "label": "确认", "primary": true }, { "type": "button", "actionType": "drawer", "label": "再弹一个", "drawer": { "title": "抽屉中的抽屉", "body": "关闭当前抽屉时，将外层抽屉一并关闭", "actions": [ { "type": "button", "label": "关闭所有", "level": "info", "close": "drawer_1" } ] } } ] } } ``` > 3.3.0 及以上版本如果是表单，可以在表单上配置 `close: false`。 ```schema: scope="body" { "type": "button", "label": "弹个框", "actionType": "drawer", "drawer": { "type": "form", "api": "/api/mock2/form/saveForm", "body": [ { "type": "input-text", "name": "name", "label": "姓名" } ], "close": false } } ``` ## 配置抽屉的按钮默认抽屉会自动生成两个按钮，一个取消，一个确认。如果通过 `actions` 来自定义配置，则以配置的为准。 ```schema: scope="body" { "type": "button-toolbar", "buttons": [ { "type": "button", "label": "无按钮", "actionType": "drawer", "drawer": { "title": "提示", "body": "这是一个没有按钮的抽屉", "actions": [] } }, { "type": "button", "label": "一个按钮", "actionType": "drawer", "drawer": { "title": "提示", "body": "只有一个 OK 的抽屉", "actions": [ { "type": "button", "actionType": "confirm", "label": "OK", "primary": true } ] } } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------------- | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- | | type | `string` | | `"drawer"` 指定为 Drawer 渲染器 | | title | [SchemaNode](../../docs/types/schemanode) | | 弹出层标题 | | body | [SchemaNode](../../docs/types/schemanode) | | 往 Drawer 内容区加内容 | | size | `string` | | 指定 Drawer 大小，支持: `xs`、`sm`、`md`、`lg`、`xl` | | position | `string` | `right` | 指定 Drawer 方向，支持: `left`、`right`、`top`、`bottom` | | className | `string` | | Drawer 最外层容器的样式类名 | | headerClassName | `string` | | Drawer 头部区域的样式类名 | | bodyClassName | `string` | `modal-body` | Drawer body 区域的样式类名 | | footerClassName | `string` | | Drawer 页脚区域的样式类名 | | showCloseButton | `boolean` | `true` | 是否展示关闭按钮，当值为 `false` 时，默认开启 closeOnOutside | | closeOnEsc | `boolean` | `false` | 是否支持按 Esc 关闭 Drawer | | closeOnOutside | `boolean` | `false` | 点击内容区外是否关闭 Drawer | | overlay | `boolean` | `true` | 是否显示蒙层 | | resizable | `boolean` | `false` | 是否可通过拖拽改变 Drawer 大小 | | width | `string \| number` | `500px` | 容器的宽度，在 `position` 为 `left` 或 `right` 时生效 | | height | `string \| number` | `500px` | 容器的高度，在 `position` 为 `top` 或 `bottom` 时生效 | | actions | Array<[Action](./action)> | 【确认】和【取消】 | 可以不设置，默认只有两个按钮。 | | data | `object` | | 支持 [数据映射](../../docs/concepts/data-mapping)，如果不设定将默认将触发按钮的上下文中继承数据。 | ## 事件表当前组件会对外派发以下事件，可以通过 `onEvent` 来监听这些事件，并通过 `actions` 来配置执行的动作，在 `actions` 中可以通过 `${事件参数名}` 或 `${event.data.[事件参数名]}` 来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | -------- | ------------------------------------------------------------------------ | ------------------ | | confirm | `event.data: object` 抽屉数据
`[name]: any` 当前数据域中指定字段的值 | 点击确认提交时触发 | | cancel | `event.data: object` 抽屉数据
`[name]: any` 当前数据域中指定字段的值 | 点击取消时触发 | ### confirm ```schema: scope="body" [ { "label": "打开", "type": "button", "onEvent": { "click": { "actions": [ { "actionType": "drawer", "drawer": { "title": "标题", "body": "这是一个抽屉", "onEvent": { "confirm": { "actions": [ { "actionType": "toast", "args": { "msg": "confirm" } } ] } } } } ] } } } ] ``` ### cancel ```schema: scope="body" [ { "label": "打开", "type": "button", "onEvent": { "click": { "actions": [ { "actionType": "drawer", "drawer": { "title": "标题", "body": "这是一个抽屉", "onEvent": { "cancel": { "actions": [ { "actionType": "toast", "args": { "msg": "cancel" } } ] } } } } ] } } } ] ``` ## 动作表当前组件对外暴露以下特性动作，其他组件可以通过指定 `actionType: 动作名称`、`componentId: 该组件id` 来触发这些动作，动作配置可以通过 `args: {动作配置项名称: xxx}` 来配置具体的参数，详细请查看[事件动作](../../docs/concepts/event-action#触发其他组件的动作)。 | 动作名称 | 动作配置 | 说明 | | -------- | -------------------------- | ------------ | | confirm | - | 确认（提交） | | cancel | - | 取消（关闭） | | setValue | `value: object` 更新的数据 | 更新数据 | ### confirm 动作 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "drawer", "drawer": { "title": "在抽屉中的表单", "id": "drawer_confirm", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "username", "required": true, "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] }, "actions": [ { "type": "button", "label": "触发确认", "onEvent": { "click": { "actions": [ { "actionType": "confirm", "componentId": "drawer_confirm" } ] } } } ] } } ``` ### cancel 动作 ```schema: scope="body" { "type": "button", "label": "弹个表单", "actionType": "drawer", "drawer": { "title": "在抽屉中的表单", "id": "drawer_cancel", "body": { "type": "form", "api": "/api/mock2/form/saveForm?waitSeconds=2", "body": [ { "type": "input-text", "name": "username", "required": true, "placeholder": "请输入用户名", "label": "用户名" }, { "type": "input-password", "name": "password", "label": "密码", "required": true, "placeholder": "请输入密码" }, { "type": "checkbox", "name": "rememberMe", "label": "记住登录" } ] }, "actions": [ { "type": "button", "label": "触发取消", "onEvent": { "click": { "actions": [ { "actionType": "cancel", "componentId": "drawer_cancel" } ] } } } ] } } ``` ### setValue 动作通过 `setValue` 更新指定抽屉的数据。 #### 合并数据默认 `setValue` 会将新数据与目标组件数据进行合并。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 覆盖数据可以通过 `"dataMergeMode": "override"` 来覆盖目标组件数据。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Zh CN Components Dropdown Button (`docs/zh-CN/components/dropdown-button.md`) --- title: DropDownButton 下拉菜单 description: type: 0 group: ⚙ 组件 menuName: DropDownButton icon: order: 44 --- ## 基本用法 ```schema { "type": "page", "body": { "type": "dropdown-button", "label": "下拉菜单", "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 分组展示模式配置`children`可以实现分组展示，分组标题支持配置`icon`。 > 1.5.7 及以上版本 ```schema: scope="body" { "type": "dropdown-button", "label": "下拉菜单", "buttons": [ { "label": "RD", "icon": "fa fa-user", "children": [ { "type": "button", "label": "前端FE" }, { "type": "button", "label": "后端RD" } ] }, { "label": "QA", "icon": "fa fa-user", "children": [ { "type": "button", "label": "测试QA", }, { "type": "button", "label": "交付测试DQA", "disabled": true }, { "type": "divider" } ] }, { "label": "Manager", "icon": "fa fa-user", "children": [ { "type": "button", "label": "项目经理PM" }, { "type": "button", "label": "项目管理中心PMO", "visible": false } ] } ] } ``` ## 关闭下拉菜单配置`"closeOnClick": true`可以实现点击按钮后自动关闭下拉菜单。 ```schema { "type": "page", "body": { "type": "dropdown-button", "label": "下拉菜单", "closeOnClick": true, "closeOnOutside": true, "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 触发方式 > 1.4.0 及以上版本默认是点击鼠标触发，可以通过 `"trigger": "hover"` 配置为鼠标移上去后触发 ```schema { "type": "page", "body": { "type": "dropdown-button", "label": "下拉菜单", "trigger": "hover", "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 设置图标通过 `icon` 可以设置左侧图标 ```schema { "type": "page", "body": { "type": "dropdown-button", "label": "下拉菜单", "trigger": "hover", "icon": "fa fa-home", "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 只显示图标可以设置 `level` 及 `hideCaret` 来只显示图标，并配合 `tooltip` 来显示提示文字 ```schema { "type": "page", "body": { "type": "dropdown-button", "level": "link", "icon": "fa fa-ellipsis-h", "hideCaret": true, "tooltip": "提示", "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 设置右侧图标 > 1.5.0 及以上版本通过 `rightIcon` 设置右侧图标，同时通过 `hideCaret` 隐藏右侧下拉图标 ```schema { "type": "page", "body": { "type": "dropdown-button", "label": "下拉菜单", "trigger": "hover", "rightIcon": "fa fa-ellipsis-v", "hideCaret": true, "buttons": [ { "type": "button", "label": "按钮1", "disabled": true }, { "type": "button", "label": "按钮2" }, { "type": "button", "label": "按钮3" } ] } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------------- | ----------------------- | ----------------- | ----------------------------------------- | | type | `string` | `dropdown-button` | 类型 | | label | `string` | | 按钮文本 | | className | `string` | | 外层 CSS 类名 | | btnClassName | `string` | | 按钮 CSS 类名 | | menuClassName | `string` | | 下拉菜单 CSS 类名 | | block | `boolean` | | 块状样式 | | size | `string` | | 尺寸，支持`'xs'`、`'sm'`、`'md'` 、`'lg'` | | align | `string` | | 位置，可选`'left'`或`'right'` | | buttons | `Array` | | 配置下拉按钮 | | iconOnly | `boolean` | | 只显示 icon | | defaultIsOpened | `boolean` | | 默认是否打开 | | closeOnOutside | `boolean` | `true` | 点击外侧区域是否收起 | | closeOnClick | `boolean` | `false` | 点击按钮后自动关闭下拉菜单 | | trigger | `click` 或 `hover` | `click` | 触发方式 | | hideCaret | `boolean` | false | 隐藏下拉图标 | | popOverContainerSelector | `string` | | 弹出的下拉按钮放在哪个节点下 | ## 事件表当前组件会对外派发以下事件，可以通过`onEvent`来监听这些事件，并通过`actions`来配置执行的动作，在`actions`中可以通过`${事件参数名}`或`${event.data.[事件参数名]}`来获取事件产生的数据，详细请查看[事件动作](../../docs/concepts/event-action)。 | 事件名称 | 事件参数 | 说明 | | ---------- | ---------------------------- | --------------------------------------- | | mouseenter | items: Array | 触发方式为 hover 模式下，鼠标移入时触发 | | mouseleave | items: Array | 触发方式为 hover 模式下，鼠标移出时触发 | ### mouseenter ```schema: scope="body" { "type": "dropdown-button", "label": "下拉按钮", "trigger": "hover", "onEvent": { "mouseenter": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "mouseenter ${event.data.items.length}" } } ] } }, "buttons": [ { "type": "button", "label": "按钮1" }, { "type": "button", "label": "按钮2" } ] } ``` ### mouseleave ```schema: scope="body" { "type": "dropdown-button", "label": "下拉按钮", "trigger": "hover", "onEvent": { "mouseleave": { "actions": [ { "actionType": "toast", "args": { "msgType": "info", "msg": "mouseleave ${event.data.items.length}" } } ] } }, "buttons": [ { "type": "button", "label": "按钮1" }, { "type": "button", "label": "按钮2" } ] } ``` ## 动作表暂无 --- ### Zh CN Components Each (`docs/zh-CN/components/each.md`) --- title: Each 循环渲染器 description: type: 0 group: ⚙ 组件 menuName: Each 循环渲染器 icon: order: 45 --- ## 基本用法通过 name 属性指定要循环的数组，items 属性指定循环的内容。 ```schema: scope="page" { "type": "page", "data": { "arr": ["A", "B", "C"] }, "body": { "type": "each", "name": "arr", "items": { "type": "tpl", "tpl": "${item} " } } } ``` ### 如果是对象数组如果数组中的数据是对象，可以直接使用内部变量 xxx 来获取，或者通过 `item.xxxx`。另外能用 index 来获取数组索引。 > 如果成员对象本身也有名字为 index 的字段就会覆盖到，获取不到索引了，请查看「循环嵌套」的章节解决 ```schema:height="160" scope="page" { "type": "page", "data": { "arr": [{"name": "a"}, {"name": "b"}, {"name": "c"}] }, "body": { "type": "each", "name": "arr", "items": { "type": "tpl", "tpl": "${name}:${index} " } } } ``` ### 循环嵌套如果存在嵌套使用，通过默认的 `item` 或者 `index` 始终是拿的最里面那层的信息，想要获取上层 each 的信息，则需要自定义 `itemKeyName` 和 `indexKeyName` 来指定字段名。 ```schema:height="160" scope="page" { "type": "page", "data": { "arr": [{"name": "a", "subList": ["a1", "a2"]}, {"name": "b", "subList": ["b1", "b2"]}, {"name": "c", "subList": ["c1", "c2"]}] }, "body": { "type": "each", "name": "arr", "itemKeyName": "itemOutter", "indexKeyName": "indexOutter", "items": [ { "type": "tpl", "inline": false, "tpl": "${name}:${index} " }, { "type": "each", "name": "subList", "items": [ { "type": "tpl", "tpl": "${itemOutter.name}-${item}:${indexOutter}-${index} " } ] } ] } } ``` ## 用作 Field 时当用在 Table 的列配置 Column、List 的内容、Card 卡片的内容和表单的 Static-XXX 中时，可以设置`name`属性，映射同名变量，然后用可以通过 `item` 变量获取单项值 ### Table 中的列类型 ```schema: scope="body" { "type": "table", "data": { "items": [ { "id": "1", "each": ["A1", "B1", "C1"] }, { "id": "2", "each": ["A2", "B2", "C2"] }, { "id": "3", "each": [] } ] }, "columns": [ { "name": "id", "label": "Id" }, { "name": "each", "label": "循环", "type": "each", "placeholder": "暂无内容", "items": { "type": "tpl", "tpl": "${item}" } } ] } ``` List 的内容、Card 卡片的内容配置同上 ### Form 中静态展示 ```schema: scope="body" { "type": "form", "data": { "each": ["A", "B", "C"] }, "body": [ { "type": "each", "label": "静态展示each", "name": "each", "items": { "type": "tpl", "tpl": "${item}" } } ] } ``` ## 使用数据映射 ```schema: scope="page" { "type": "page", "data": { "arr": ["A", "B", "C"] }, "body": { "type": "each", "source": "${arr}", "items": { "type": "tpl", "tpl": "${item} " } } } ``` `name` 的优先级会比 `source` 更高 ## 动态表单项 > 3.5.0 版本开始支持表单项支持通过表达式配置动态表单项，可结合 `each` 组件一起使用。 ```schema: scope="page" { "type": "page", "data": { "arr": ["A", "B", "C"] }, "body": [ { type: "form", debug: true, body: [ { "type": "each", "source": "${arr}", "items": { "type": "input-text", "label": "Input${item}", "name": "text${index}" } } ] } ] } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------ | -------- | -------- | -------------------------------------------------------------------- | | type | `string` | `"each"` | 指定为 Each 组件 | | value | `array` | `[]` | 用于循环的值 | | name | `string` | | 获取数据域中变量 | | source | `string` | | 获取数据域中变量，支持 [数据映射](../../docs/concepts/data-mapping) | | items | `object` | | 使用`value`中的数据，循环输出渲染器。 | | placeholder | `string` | | 当 `value` 值不存在或为空数组时的占位文本 | | itemKeyName | `string` | `item` | 获取循环当前数组成员 | | indexKeyName | `string` | `index` | 获取循环当前索引 | --- ### Zh CN Components Flex (`docs/zh-CN/components/flex.md`) --- title: Flex 布局 description: type: 0 group: ⚙ 组件 menuName: Flex 布局 icon: order: 47 --- Flex 布局是基于 CSS Flex 实现的布局效果，它比 Grid 和 HBox 对子节点位置的可控性更强，比用 CSS 类的方式更易用，并且默认使用水平垂直居中的对齐。 ## 基本用法 ```schema: scope="body" { "type": "flex", "items": [{ "style": { "backgroundColor": "#1A5CFF", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }, { "style": { "backgroundColor": "#46C93A", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }, { "style": { "backgroundColor": "#FF4757", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }] } ``` 其中 `items` 里的每一个都可以是其他 amis 类型。 ## 子节点水平分布 > 严格来说并不一定是水平，因为还能通过 direction 修改方向，不过这里为了简化就这么称呼了可以通过 justify 控制水平分布方式，默认是 `center` 居中，其他几种的示例如下： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 垂直方向位置可以通过设置 `alignItems` 改变在子节点在垂直方向的位置，默认是 `center` 居中，其他几个常见设置请参考： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 布局方向默认是行的方式，可以通过 "direction": "column" 改成列的方式。 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 移动端支持有时候希望在移动端有不同展现，比如将 `direction` 改成 `column`： ```schema: scope="body" { "type": "flex", "mobile": { "direction": "column" }, "items": [{ "style": { "backgroundColor": "#1A5CFF", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }, { "style": { "backgroundColor": "#46C93A", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }, { "style": { "backgroundColor": "#FF4757", "width": 100, "height": 50, "margin": 5 }, "type": "tpl", "tpl": "" }] } ``` 其他关于移动端定制的细节请参考[这里](../docs/extend/mobile)。 ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ---------- | -------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- | | type | `string` | `flex` | 指定为 Flex 渲染器 | | className | `string` | | css 类名 | | justify | `string` | | "start", "flex-start", "center", "end", "flex-end", "space-around", "space-between", "space-evenly" | | alignItems | `string` | | "stretch", "start", "flex-start", "flex-end", "end", "center", "baseline" | | style | `object` | | 自定义样式 | | items[] | [SchemaNode](../docs/types/schemanode) | | --- ### Zh CN Components Grid 2d (`docs/zh-CN/components/grid-2d.md`) --- title: Grid 2D 布局 description: type: 0 group: ⚙ 组件 menuName: Grid 2D 组件 icon: order: 47 --- Grid 2D 是一种二维布局方式，它可以更直观设置组件位置。 > Grid 2D 布局不支持 IE11 ## 基本用法 ```schema: scope="body" { "type": "grid-2d", "grids": [ { "x": 1, "y": 1, "h": 1, "w": 6, "gridClassName": "bg-green-300", "type": "tpl", "tpl": "[grid-1] x:1 y:1 h:1 w:6" }, { "x": 7, "y": 1, "h": 1, "w": 6, "gridClassName": "bg-blue-300", "type": "tpl", "tpl": "[grid-2] x:7 y:1 h:1 w:6" }, { "x": 1, "y": 2, "h": 2, "w": 4, "gridClassName": "bg-red-300", "type": "tpl", "tpl": "[grid-3] x:1 y:2 h:2 w:4" }, { "x": 5, "y": 2, "h": 1, "w": 8, "gridClassName": "bg-purple-300", "type": "tpl", "tpl": "[grid-4] x:5 y:2 h:1 w:8" } ] } ``` ## 布局基础 `grids` 中可以是任意组件，这里为了简化使用 tpl 组件，通过 x/y/h/w 这四个属性来控制格子的位置和大小。首先看下图示例，它就是前面基本用法的示例加上标注：默认水平方向会平分为 12 列，可以通过 `cols` 来调整，比如只分为 3 栏。先看 `[grid-1]`，它的 `x/y/h/w` 值分别是 `1,1,1,6`： - `x,y` 决定这个格子的位置，`1,1` 就是最左上角的位置，如图所示 - `w` 代表宽度占几格，因为水平方向一共 12 列，所以 6 就意味着占水平空间一半 - `h` 代表高度占几格，默认每行高度可以使用 `rowHeight` 来控制，也可以设置 `height` 来单独控制这一行的高度其它格子也可以参照这张图推理出来，比如 `[grid-2]` 起始 x 位置是 `7`，宽度是 6，因此它和 `[grid-]` 平分了第一行。 ## 独立设置高宽在上面的例子中格子的宽度是根据页面宽度平分，高度是固定的，但我们也可以单独改变某一行或某一列的高宽，方法是格子上的 `width` 和 `height` 值。看下面这个例子 ```schema: scope="body" { "type": "grid-2d", "cols": 3, "grids": [ { "x": 1, "y": 1, "h": 1, "w": 1, "width": 100, "gridClassName": "bg-green-300", "type": "tpl", "tpl": "[grid-1] x:1 y:1 h:1 w:1" }, { "x": 2, "y": 1, "h": 1, "w": 1, "height": 100, "gridClassName": "bg-blue-300", "type": "tpl", "tpl": "[grid-2] x:2 y:1 h:1 w:1" }, { "x": 3, "y": 1, "h": 1, "w": 1, "width": 100, "gridClassName": "bg-red-300", "type": "tpl", "tpl": "[grid-3] x:3 y:1 h:1 w:1" }, { "x": 2, "y": 2, "h": 1, "w": 1, "gridClassName": "bg-purple-300", "type": "tpl", "tpl": "[grid-4] x:2 y:2 h:1 w:1" } ] } ``` 在这个例子中，首先通过 `cols` 设置了列数为 `3`，然后将 `[grid-1]` 和 `[grid-3]` 的 width 设置为 `100`，使得这两列的宽度都是 100，而页面剩下的宽度就全都留给了 `[grid-2]`。而在 `[grid-2]` 中通过 `height` 设置了高度，使得这一行高度是 `100px`，而不是默认的 `50px`。请注意：`width` 将影响一整列，`height` 将影响一整行。 ## 自适应内容高度如果格子内容高度不确定，想更具内容自动撑开，可以设置 `height` 为 `auto`。 ```schema: scope="body" { "type": "grid-2d", "cols": 3, "grids": [ { "x": 2, "y": 1, "h": 1, "w": 1, "height": "auto", "gridClassName": "bg-blue-300", "type": "tpl", "tpl": "1
2
3
4
5
6
" } ] } ``` ## 格子间距 gap / rowGap 通过 grip 上的 gap 属性来控制间距，默认包含水平和垂直间距 ```schema: scope="body" { "type": "grid-2d", "gap": 10, "gapRow": 5, "grids": [ { "x": 1, "y": 1, "h": 1, "w": 6, "gridClassName": "bg-green-300", "type": "tpl", "tpl": "[grid-1] x:1 y:1 h:1 w:6" }, { "x": 7, "y": 1, "h": 1, "w": 6, "gridClassName": "bg-blue-300", "type": "tpl", "tpl": "[grid-2] x:7 y:1 h:1 w:6" }, { "x": 1, "y": 2, "h": 2, "w": 4, "gridClassName": "bg-red-300", "type": "tpl", "tpl": "[grid-3] x:1 y:2 h:2 w:4" }, { "x": 5, "y": 2, "h": 1, "w": 8, "gridClassName": "bg-purple-300", "type": "tpl", "tpl": "[grid-4] x:5 y:2 h:1 w:8" } ] } ``` ## 内容区域小于格子的摆放默认情况下，格子的高宽会撑满对应区域的高宽，但有时候内容高宽比这个格子小，比如一张图片，如何将它在各种中居中显示？看下面的例子 ```schema: scope="body" { "type": "grid-2d", "cols": 3, "grids": [ { "x": 1, "y": 1, "h": 1, "w": 1, "gridClassName": "bg-green-300", "type": "tpl", "tpl": "[grid-1] x:1 y:1 h:1 w:1" }, { "x": 2, "y": 1, "h": 1, "w": 1, "align": "center", "valign": "middle", "gridClassName": "bg-blue-300", "type": "tpl", "tpl": "hello" }, { "x": 3, "y": 1, "h": 1, "w": 1, "gridClassName": "bg-red-300", "type": "tpl", "tpl": "[grid-3] x:3 y:1 h:1 w:1" } ] } ``` 在中间的格子中，我们设置了 `"align": "center"` 和 `"valign": "middle"`，就使得文字水平和垂直居中显示了。 ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | --------------- | ----------------------------------------- | --------- | ------------------------------- | | type | `string` | `grid-2d` | 指定为 Grid 2D 渲染器 | | gridClassName | `string` | | 外层 Dom 的类名 | | gap | `int`/`string` | 0 | 格子间距，包括水平和垂直 | | cols | `int` | 12 | 格子水平划分为几个区域 | | rowHeight | `int` | 50 | 每个格子默认垂直高度 | | rowGap | `int`/`string` | | 格子垂直间距 | | grids | `Array` | | 格子集合 | | grids[x] | [SchemaNode](../../docs/types/schemanode) | | 格子可以是其他渲染器 | | grids[x].x | `int` | | 格子起始位置的横坐标 | | grids[x].y | `int` | | 格子起始位置的纵坐标 | | grids[x].w | `int` | | 格子横跨几个宽度 | | grids[x].h | `int` | | 格子横跨几个高度 | | grids[x].width | `int`/`string`/`auto` | | 格子所在列的宽度 | | grids[x].height | `int`/`string`/`auto` | | 格子所在行的高度，可以设置 auto | | grids[x].align | `left`/`center`/`right`/`auto` | `auto` | 格子内容水平布局 | | grids[x].valign | `top`/`bottom`/`middle`/`auto` | `auto` | 格子内容垂直布局 | --- ### Zh CN Components Grid Nav (`docs/zh-CN/components/grid-nav.md`) --- title: GridNav 宫格导航 description: type: 0 group: ⚙ 组件 menuName: GridNav 宫格导航 icon: order: 54 --- 宫格菜单导航，不支持配置初始化接口初始化数据域，所以需要搭配类似像`Service`、`Form`或`CRUD`这样的，具有配置接口初始化数据域功能的组件，或者手动进行数据域初始化，然后通过`source`属性，获取数据链中的数据，完成菜单展示。 ## 基本用法通过 source 关联上下文数据，或者通过 name 关联。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": [ { "type": "grid-nav", "source": "${items}" }, { "type": "divider" }, { "type": "grid-nav", "name": "items" } ] } ``` 也可以静态展示，即不关联数据固定显示。 ```schema { "type": "page", "body": { "type": "grid-nav", "options": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] } } ``` ## 自定义列数默认一行展示四个格子，可以通过 `columnNum` 自定义列数 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" } ] }, "body": { "type": "grid-nav", "columnNum": 3, "source": "${items}" } } ``` ## 正方形格子设置 `square` 属性后，格子的高度会和宽度保持一致。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "source": "${items}", "square": true } } ``` ## 格子间距通过 `gutter` 属性设置格子之间的距离。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "source": "${items}", "gutter": 20 } } ``` ## 内容横排将 `direction` 属性设置为 `horizontal`，可以让宫格的内容呈横向排列。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "direction": "horizontal", "source": "${items}" } } ``` ## 图标占比设置 `iconRatio` 可以控制图标宽度占比，默认 60%，设置 1-100 的数字。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "iconRatio": "40", "source": "${items}" } } ``` ## 角标提示设置 badge 属性后，会在图标右上角展示相应的角标，支持红点、数字、彩带模式。 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "导航1", "badge": { "mode": "text", "text": "10" } }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "导航2", "badge": { "mode": "dot" } }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "导航3", "badge": { "mode": "ribbon", "text": "热销" } }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "source": "${items}", "border": false } } ``` ## 点击交互设置 clickAction 属性支持通用点击交互，详见 [Action](./action) 配置 ```schema { "type": "page", "data": { "items": [ { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-1.png", "text": "外部跳转", "link": "https://www.baidu.com", "blank": true }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-2.png", "text": "弹框", "clickAction": { "actionType": "dialog", "dialog": { "title": "弹框", "body": "这是个简单的弹框。" } } }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-3.png", "text": "内部跳转", "link": "/docs/index" }, { "icon": "https://aisuda-public-images.bj.bcebos.com/amis/icon-4.png", "text": "导航4" } ] }, "body": { "type": "grid-nav", "source": "${items}", "border": false } } ``` ## 属性表 | 属性名 | 类型 | 默认值 | 说明 | | ------------------- | --------------- | ---------- | -------------------------------------------------------- | | type | `string` | `grid-nav` | | | className | `string` | | 外层 CSS 类名 | | itemClassName | `string` | | 列表项 css 类名 | | contentClassName | `string` | | 列表项内容 css 类名 | | value | `Array