vendor: amis 6.13.0 base (fork root)

This commit is contained in:
2026-06-16 22:14:57 +08:00
commit 8c8e4247a9
3840 changed files with 2467374 additions and 0 deletions

View File

@@ -0,0 +1,60 @@
---
title: 行为
description:
type: 0
group: 💡 概念
menuName: 行为
icon:
order: 12
---
页面的交互操作,例如:**提交表单、显示一个弹框、跳转页面、复制一段文字到粘贴板**等等操作,都可以视作页面的一种**行为**。
在 amis 中,大部分 **行为** 是跟 **行为按钮组件** 进行绑定的,也就是说,当你想要配置一个行为,大部分情况下你应该遵循下面的步骤:
1. 添加一个 **行为按钮组件**;
2. 配置当前 **行为类型(actionType)**;
3. 根据当前行为类型,配置你想要的 **属性**。
## 如何配置行为?
### 通过行为按钮
```schema: scope="body"
{
"type": "action",
"label": "发出一个请求",
"actionType": "ajax",
"api": "/api/mock2/form/saveForm"
}
```
1. 在`page`内容区中,添加一个`action`行为按钮组件
2. 配置当前行为类型是 ajax(即发送一个 ajax 请求)
3. 配置请求 api,值为 API 类型
现在点击该按钮,你会发现浏览器发出了这个`ajax`请求。
很简单是吧?我们再来一个例子:
```schema: scope="body"
{
"type": "action",
"label": "弹个框",
"actionType": "dialog",
"dialog": {
"title": "弹框",
"body": "Hello World!"
}
}
```
这次我们配置`actionType`为`dialog`,意味着点击该按钮会弹出一个模态框,并配置`dialog`内容,来显示字符串`Hello World!`
> `dialog`是容器,也就意味着可以在`body`属性中配置其他组件
完整的行为列表可以查看 [action](../../components/action)组件
### 组件所支持的行为
一些特殊组件,例如 Chart 组件 中的图表点击行为,可以直接配置`clickAction`,来配置行为对象。

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,533 @@
---
title: 数据域与数据链
description:
type: 0
group: 💡 概念
menuName: 数据域与数据链
icon:
order: 10
---
## 基本的数据展示
我们再看之前的简单示例:
```json
{
"type": "page",
"body": "Hello World!"
}
```
目前我们只是在 `Page` 组件中渲染一串固定的文本,如何实现 **通过接口拉取想要的数据,并展示到 `Page` 组件的内容区** 呢?
## 添加初始化接口
```json
{
"type": "page",
"initApi": "/api/mock2/page/initData",
"body": "date is ${date}"
}
```
这个 api 接口返回的数据结构如下:
```json
{
"status": 0,
"msg": "",
"data": {
"title": "Test Page Component",
"date": "2017-10-13"
}
}
```
渲染后页面效果:
```schema
{
"type": "page",
"initApi": "/api/mock2/page/initData",
"body": "date is ${date}"
}
```
## 发生了什么?
我们可以看到,输出结果不变,但是我们这次渲染的是接口返回的数据:
1. 首先我们给 `Page` 组件配置了`initApi`属性,该属性会在组件初始化时,请求所该属性所配置的接口
2. 接口请求成功后,`Page` 会把接口返回的`data`内数据存到当前的数据域中
3. `Page` 在渲染 `body` 所配置的文本时,会解析文本内容,当解析到模板变量`${text}`时,amis 会把尝试在当前组件的数据域中获取`text`变量值,并替换掉`${text}`,最后渲染解析后的文本。
> 下一节我们会介绍[模板](./template),`body`属性自身支持模板语法,amis 中支持模板语法的组件还有很多
## 数据域
前面我们提到了**数据域**这个概念,它是 amis 中最重要的概念之一。
还是通过最简单的示例进行讲解:
```json
{
"type": "page",
"body": "Hello ${text}"
}
```
上面的配置要做的很简单:使用 `Page` 组件,在内容区内渲染一段模板文字,其中`${text}`是**模板变量**,它会去到当前组件的数据域中,获取`text`变量值。
毫无疑问,`${text}`将会解析为空白文本,最终渲染的文本是 `Hello`
```schema
{
"type": "page",
"body": "Hello ${text}"
}
```
因为当前 `Page` 组件的数据域中是没有任何数据的,相比之前的示例,区别在于前面我们为 `Page` 组件配置了初始化接口,它会将接口返回的数据存入数据域中以供组件使用。
再观察下面这段配置:
```schema
{
"data": {
"text": "World!"
},
"type": "page",
"body": "Hello ${text}"
}
```
再次查看渲染结果,顺利输出了 `Hello World!`
相信你可能已经猜到,**组件的`data`属性值是数据域的一种形式**,实际上当我们没有显式的配置数据域时,可以假想成这样:
```schema
{
"data": {}, // 空的数据域
"type": "page",
"body": "Hello ${text}"
}
```
> 而前面我们知道 amis 的特性之一是基于组件树,因此自然数据域也会形成类似于树型结构,如何来处理这些数据域之间的联系呢,这就是我们马上要介绍到的 **[数据链](./datascope-and-datachain#%E6%95%B0%E6%8D%AE%E9%93%BE)**
## 数据链
相信通过上文,你已经基本掌握了 amis 中数据域的概念,接下来我们会介绍另一个重要概念:**数据链**。
**数据链**的特性是,当前组件在遇到获取变量的场景(例如模板渲染、展示表单数据、渲染列表等等)时:
1. 首先会先尝试在当前组件的数据域中寻找变量,当成功找到变量时,通过数据映射完成渲染,停止寻找过程;
2. 当在当前数据域中没有找到变量时,则向上寻找,在父组件的数据域中,重复步骤`1`和`2`;
3. 一直寻找,直到顶级节点,也就是`page`节点,寻找过程结束。
4. 但是如果 url 中有参数,还会继续向上查找这层,所以很多时候配置中可以直接 `${id}` 取地址栏参数。
> 为了方便讲解,我们这一章的例子统一使用的设置组件`data`属性的方式来初始化数据域,请记住,如果组件支持,你永远可以通过接口来进行数据域的初始化
继续来看这个例子:
```schema
{
"type": "page",
"data": {
"name": "zhangsan",
"age": 20
},
"body": [
{
"type": "tpl",
"tpl": "my name is ${name}"
},
{
"type": "service",
"data": {
"name": "lisi"
},
"body": {
"type": "tpl",
"tpl": "my name is ${name}, I'm ${age} years old"
}
}
]
}
```
上面的配置项形成了如下的组件树和数据链:
组件树:
```
page
├─ tpl
└─ service
└─ tpl
```
数据链:
```json
{
"name": "zhangsan",
"age": 20,
"__sub": {
"name": "lisi"
}
}
```
> `__sub` 字段只是为了方便理解。
首先,`page`组件下的`tpl`组件,在渲染`my name is ${name}`时,首先会在`page`的数据域中,尝试寻找`name`变量,在当前数据域中,`name`变量为`zhangsan`,因此寻找变量结束,通过数据映射渲染,输出:`my name is zhangsan`,渲染结束;
然后,`service`组件开始渲染,`service`组件内子组件`tpl`,它配置的模板字符串是:`my name is ${name}, I'm ${age} years old`,它会在`service`的数据域中,尝试寻找`name`和`age`变量。
由代码可以看出,`service`数据域中`name`变量为`lisi`,因此停止该变量的寻找,接下来寻找`age`变量。
很明显在`service`数据域中寻找`age`变量会失败,因此向上查找,尝试在`page`数据域中寻找`age`变量,找到为`20`,寻找变量结束,通过数据映射渲染,输出:`my name is lisi, I'm 20 years old`,渲染结束。
> **注意:** 当前例子中,对数据域中数据的获取使用的是 **\${xxx}** 模板语法,但是在不同的组件配置项中,获取数据的语法会有差异,我们会在后续的[模板](./template)和[表达式章节](./expression)中一一介绍。
### 具备数据域的组件
- App
- Page
- Cards
- Chart
- CRUD
- CRUD2
- Dialog
- Drawer
- List
- Form
- PaginationWrapper
- Service
- Wizard
- Combo
- InputArray
- Table
- Table2
有个特殊情况是 CRUD 中 filter,实际上是个 form,所以 CRUD 中有两层数据域,第一层是 CRUD 本身,同时查询条件表单中也有一层数据域。
### 常见误解
需要注意,只有少数几个容器组件会创建新的数据域,具体查看[具备数据域的组件](#具备数据域的组件)列表。
常见的错误写法是给容器组件加 data 属性,比如:
```schema
{
"type": "page",
"data": {
"name": "zhangsan"
},
"body": [
{
"type": "tpl",
"tpl": "my name is ${name}"
},
{
"type": "container",
"data": {
"name": "lisi"
},
"body": {
"type": "tpl",
"tpl": "my name is ${name}"
}
}
]
}
```
这样是不会生效的,正确的做法是使用 Service 包裹一层,如下所示
```schema
{
"type": "page",
"data": {
"name": "zhangsan"
},
"body": [
{
"type": "tpl",
"tpl": "my name is ${name}"
},
{
"type": "service",
"data": {
"name": "lisi"
},
"body": {
"type": "container",
"body": {
"type": "tpl",
"tpl": "my name is ${name}"
}
}
}
]
}
```
## 初始化数据域
通过上面的介绍你可能发现,初始化数据域有两种方式:
### 1. 配置组件初始化接口
想要将自己的服务中的数据保存到某个组件的数据域中,最好的方式就是为当前组件配置初始化接口:
```json
{
"type": "page",
"initApi": "/api/initData",
"body": "Hello ${text}"
}
```
接口必须按照下面的格式返回:
```json
{
"status": 0,
"msg": "",
"data": {
"text": "World!"
...其他字段
}
}
```
**注意:**
1. **并不是所有组件都支持配置初始化接口来实现数据域初始化操作**,对于那些不支持配置初始化接口的组件来说,一般会使用 [**Service 组件**](../../components/service) 来辅助实现数据域初始化;
2. **`status`**、**`msg`** 和 **`data`** 字段为接口返回的必要字段;
3. `data`必须返回一个具有`key-value`结构的对象
```json
{
"status": 0,
"msg": "",
"data": { // 正确
"text": "World!"
}
}
// 直接返回字符串或者数组都是无效的
{
"status": 0,
"msg": "",
"data": "some string" // 错误,使用 key 包装
}
{
"status": 0,
"msg": "",
"data": ["a", "b"] // 错误,使用 key 包装
}
```
> `api` 除了配置字符串格式以外,还可以配置复杂对象结构,更多详情查看[API 文档](../types/api)
### 2. 显式配置 data 属性值
另一种初始化当前数据域的方式是显式的设置组件的`data`属性值:
```schema
{
"data": {
"text": "World!",
"name": "amis"
},
"type": "page",
"body": "Hello ${text}, my name is ${name}."
}
```
### 同时配置
在同时配置 **初始化接口** 和 **`data`属性** 时,数据域将会合并`data`属性值和初始化接口返回的数据
## 更新数据域
部分组件的某些交互或行为会对当前组件的数据域进行更新:
```schema
{
"type": "page",
"body": {
"type": "form",
"api": "/api/mock2/form/saveForm",
"body": [
{
"type": "input-text",
"name": "name",
"label": "姓名:"
},
{
"type": "input-text",
"name": "age",
"label": "年龄:"
},
{
"type": "static-tpl",
"tpl": "生成的id为:${id}"
}
]
}
}
```
`/api/saveForm`接口会保存当前表单提交的数据,并返回后端服务生成的`id`,并返回到前端,格式如下;
```json
{
"status": 0,
"msg": "保存成功",
"data": {
"id": 1
}
}
```
这时 amis 将会把`data`数据与当前`form`组件的数据域进行**merge**,`form`组件中的`static-tpl`组件会根据更新后的数据域,显示`id`为`1`。
> 具有类似特征的组件还有`Formula`等
## 更新数据链
通常顶层数据域数据更新,孩子中具备数据域的组件都会更新,如果不更新会拿不到最新的值。从功能来看这个更新代价其实是很大的,有性能损耗,比如如果我在顶层更新了个变量 `name`,所有的孩子都会重新刷新一遍。
目前 amis 中,具备数据域的组件,默认会检测两层节点的数据是否发生变化(上层数据域和上上层数据域),来决定当前层的数据要不要更新。存在两个问题:
1. 当前组件也许并不关心上层数据是否变化,没必要进行这些刷新操作
2. 当前组件关心上上层的数据变化,但是在此拿不到最新的。(比如:放在 service 中的 crud,crud 中 filter 用了 service 的接口返回数据,但是拿不到最新的)
amis 从 3.2.0 版本开始针对[具备数据域的组件](#具备数据域的组件)新增了 `trackExpression` 属性,用来主动配置当前组件需要关心的上层数据。
针对以上问题,则可以通过这样配置来解决
1. `trackExpression` 配置成 `"none"` 也就是说不追踪任何数据。
2. `trackExpression` 配置成 `"${xxxVariable}"` 这样 xxxVariable 变化了更新当前组件的数据链。
关于 `trackExpression` 的语法,请查看表达式篇章,可以监听多个变量比如: `"${xxx1},${xxx2}"`,还可以写表达式如 `"${ xxx ? xxx : yyy}"`。
amis 内部是通过运算这个表达式的结果来判断。所以表达式中千万不要用随机函数,或者用当前时间等,否则每次都会更新数据链。另外如果变量是数组,或者对象,会转成统一的字符串 `[object Array]` 或者 `[object Object]` 这个其实会影响检测的,所以建议转成 json 字符串如。 `${xxxObject | json}`。还有就是既然是监控上层数据,表达式中不要写当前层数据变量,是取不到的。
```schema
{
"data": {
"name": "amis"
},
"type": "page",
"body": [
{ "label": "请修改输入框", "type": "input-text", "name": "name"},
{
"type": "switch",
"label": "同步更新",
"name": "syncSwitch"
},
{
"type": "crud",
"filter": {
"trackExpression": "${syncSwitch ? name : ''}",
"body": [
"my name is ${name}"
]
}
}
]
}
```
## URL 参数
url 中的参数会进入顶层数据域,比如下面的例子,可以点击[这里](./datascope-and-datachain?word=myquery#url-参数)看效果。
```schema
{
"type": "page",
"body": "${word}"
}
```
## 隐藏数据
数据中还有以下字段不会被枚举到,但是可以读取:
- `__prev` 修改前的值
- `__changeReason` 修改原因
- `__changeReason.type` 修改原因类型
- `input` 用户输入
- `api` api 接口返回触发
- `formula` 公式计算触发
- `hide` 隐藏属性变化触发
- `init` 表单项初始化触发
- `action` 事件动作触发
- `__super` 数据链的上一级
> `__changeReason` 字段在 amis 6.9.0 版本开始支持
```schema
{
"data": {
"name": "amis"
},
"type": "form",
id: "form_data",
"actions": [
{
type: "button",
label: "接口获取",
actionType: "ajax",
api: {
"method": "get",
url: "/api/mock2/form/saveForm",
mockResponse: {
status: 200,
data: {
name: "amis-demo"
}
}
}
},
{
type: "button",
label: "设置值",
onEvent: {
click: {
actions: [
{
"actionType": "setValue",
"componentId": "form_data",
"args": {
"value": {
"name": "amis-demo2"
}
}
}
]
}
}
},
],
"body": [
{
type: "input-text",
name: "name",
label: "姓名"
},
{
type: "tpl",
tpl: "当前值:${name}<br />修改前的值:${__prev.name}<br />变化原因:${__changeReason|json}"
}
]
}
```

File diff suppressed because it is too large Load Diff

243
docs/zh-CN/concepts/expression.md Executable file
View File

@@ -0,0 +1,243 @@
---
title: 表达式
description:
type: 0
group: 💡 概念
menuName: 表达式
icon:
order: 13
---
## 使用场景
amis 中有很多场景会用到表达式。
- 模板中变量取值。 如:`my name is ${xxx}`
- api 地址参数取值 如 `http://mydomain.com/api/xxx?id=${id}`
- api 发送&接收数据映射
```
{
"type": "crud",
"api": {
method: "post"
url: "http://mydomain.com/api/xxx",
data: {
skip: "${(page - 1) * perPage}",
take: "${perPage}"
}
},
...
}
```
- 组件显示与隐藏条件
```
{
"name": "xxxText",
"type": "input-text",
"visibleOn": "${ xxxFeature.on }"
}
```
- 表单默认值
```
{
"name": "xxxText",
"type": "input-text",
"value": "${ TODAY() }"
}
```
- 等等
amis 中表达式有两种语法:
- 一种是纯 js 表达式,如 `data.xxx === 1`。
- 另一种是用 `${` 和 `}` 包裹的表达式。如:`${ xxx === 1}`。
```json
{
"type": "tpl",
"tpl": "当前作用域中变量 show 是 1 的时候才可以看得到我哦~",
"visibleOn": "${show === 1}"
}
```
第一种是早期的版本,偷懒直接用的 [Javascript](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript),灵活性虽高,但是安全性欠佳。建议使用新版本规则,新规则跟 tpl 模板取值规则完全一样,不用来回切换语法。
## 表达式语法
表达式主要由三部分组成:开始字符、表达式内容和结束字符。其中开始字符固定是 `${` 结束字符固定是 `}`,中间内容才是表达式正文。这里说的语法主要还是表达式正文的语法。
规则主要包含:
- 变量名: `xxx变量`、`xxx变量.xxx属性`、`xxx变量[xxx属性]`
- 布尔值: `true` 或者 `false`
- null:`null`
- undefined: `undefined`
- 数字: `123` 或者 `123.23`
- 字符串: `"string"` 或者 `'string'`
- 字符模板
```
`my name is ${name}`
```
- 数组: `[1, 2, 3]`
- 对象: `{a: 1, b: 2}`
- 组合使用如: `{a: 1: b: [1, 2, 3], [key]: yyy变量}`
- 三元表达式: `xx变量 == 1 ? 2 : 3`
- 二元表达式: `xx变量 && yy 变量` 、 `xx变量 || yy 变量`、 `xx变量 == 123`
- `+` 相加
- `-` 相减
- `*` 乘
- `/` 除
- `**` pow 运算
- `||` 或者
- `&&` 并且
- `|` 或运算
- `^` 异或运算
- `&` 与运算
- `==` 等于比较
- `!=` 不等于
- `===` 恒等于
- `!==` 不恒等于
- `<` 小于
- `<=` 小于或等于
- `>` 大于
- `>=` 大于或等于
- `<<` 左移
- `>>` 右移
- `>>>` 带符号位的右移运算符
- 一元表达式: `!xx变量`、`~xx变量`
* `+` 一元加法
* `-` 一元减法
* `~` 否运算符,加 1 取反
* `!` 取反
- 函数调用:`SUM(1, 2, 3)`
- 箭头函数:`() => abc` 注意这个箭头函数只支持单表达式,不支持多条语句。主要配置其他函数使用如:`ARRAY_MAP(arr, item => item.abc)`
- 括号包裹,修改运算优先级:`(10 - 2) * 3`
示例:
```schema
{
"type": "page",
"data": {
"a": 1,
"key": "y",
"obj": {
"x": 2,
"y": 3
},
"arr": [1, 2, 3]
},
"body": [
"a is ${a} <br />",
"a + 1 is ${a + 1} <br />",
"obj.x is ${obj.x} <br />",
"obj['x'] is ${obj['x']} <br />",
"obj[key] is ${obj[key]} <br />",
"arr[0] is ${arr[0]} <br />",
"arr[a] is ${arr[a]} <br />",
"arr[a + 1] is ${arr[a + 1]} <br />"
]
}
```
_特殊字符变量名_
> 1.6.1 及以上版本
默认变量名不支持特殊字符比如 `${ xxx.yyy }` 意思取 xxx 变量的 yyy 属性,如果变量名就是 `xxx.yyy` 怎么获取?这个时候需要用到转义语法,如:`${ xxx\.yyy }`
### 公式
除了支持简单表达式外,还集成了很多公式(函数)如 `${ AVG(1, 2, 3, 4)}`:
```schema
{
"type": "page",
"data": {
"a": "",
"语文成绩": 81
},
"body": [
"1, 2, 3, 4 的平均数位 ${ AVG(1, 2, 3, 4)}",
"当前成绩:${IF(语文成绩 > 80, '优秀', '继续努力')}"
]
}
```
## 函数调用示例
函数支持嵌套,参数支持常量及变量
```schema
{
"type": "page",
"body": [
{
"type": "form",
"wrapWithPanel": false,
"data": {
"val": 3.5
},
"body": [
{
"type": "static",
"label": "IF(true, 2, 3)",
"tpl": "${IF(true, 2, 3)}"
},
{
"type": "static",
"label": "MAX(1, -1, 2, 3, 5, -9)",
"tpl": "${MAX(1, -1, 2, 3, 5, -9)}"
},
{
"type": "static",
"label": "ROUND(3.5)",
"tpl": "${ROUND(3.5)}"
},
{
"type": "static",
"label": "ROUND(val)",
"tpl": "${ROUND(val)}"
},
{
"type": "static",
"label": "AVG(4, 6, 10, 10, 10)",
"tpl": "${AVG(4, 6, 10, 10, 10)}"
},
{
"type": "static",
"label": "UPPERMONEY(7682.01)",
"tpl": "${UPPERMONEY(7682.01)}"
},
{
"type": "static",
"label": "TIMESTAMP(DATE(2021, 11, 21, 0, 0, 0), 'x')",
"tpl": "${TIMESTAMP(DATE(2021, 11, 21, 0, 0, 0), 'x')}"
},
{
"type": "static",
"label": "DATETOSTR(NOW(), 'YYYY-MM-DD')",
"tpl": "${DATETOSTR(NOW(), 'YYYY-MM-DD')}"
}
]
}
]
}
```
下面是目前所支持函数的使用手册
!!!include(amis-formula/lib/doc.md)!!!

644
docs/zh-CN/concepts/linkage.md Executable file
View File

@@ -0,0 +1,644 @@
---
title: 联动
description:
type: 0
group: 💡 概念
menuName: 联动
icon:
order: 14
---
上一节我们介绍了表达式的概念,而表达式应用最多的场景,是实现页面的联动效果。
## 基本联动
元素的联动是页面开发中很常见的功能之一,类似于:
- 某个条件下显示或隐藏某个组件
- 某个条件下请求接口
- 某个条件下轮询接口停止轮询
- 等等...
> 联动配置项一般都是 [表达式](./expression)
### 组件配置联动
控制组件的显隐,表单项的禁用状态等,看下面这个例子:
```schema: scope="body"
{
"type": "form",
"body": [
{
"type": "radios",
"name": "foo",
"label": false,
"options": [
{
"label": "类型1",
"value": 1
},
{
"label": "类型2",
"value": 2
}
]
},
{
"type": "input-text",
"name": "text1",
"label": false,
"placeholder": "选中 类型1 时可见",
"visibleOn": "${foo == 1}"
},
{
"type": "input-text",
"name": "text2",
"label": false,
"placeholder": "选中 类型2 时不可点",
"disabledOn": "${foo == 2}"
}
]
}
```
上面实例主要为一个表单,表单内有三个组件:一个`radio`, 两个`text`,通过配置联动配置项,实现下面联动效果:
1. 只要当`radio`选中`类型1`时,才会显示`text1`;
2. 当`radio`选中`类型2`时,`text2`将会变为`禁用状态`
> **注意:**
>
> 在表单项联动中,为了方便数据的读取,赋值后或者修改过的表单项,通过隐藏后,并不会在当前数据域中删除掉该字段值,因此默认提交的时候可能仍然会带上已隐藏表单项的值。
>
> 如果想要在提交时去掉某个隐藏的字段,可以通过添加 [clearValueOnHidden](../../components/form/formitem#隐藏时删除表单项值) 属性实现。
### 接口联动
#### 基本使用
接口联动是另外一种很常见的场景,查看下面这个例子:
```schema: scope="body"
{
"title": "",
"type": "form",
"mode": "horizontal",
"body": [
{
"label": "选项1",
"type": "radios",
"name": "a",
"inline": true,
"options": [
{
"label": "选项A",
"value": 1
},
{
"label": "选项B",
"value": 2
},
{
"label": "选项C",
"value": 3
}
]
},
{
"label": "选项2",
"type": "select",
"size": "sm",
"name": "b",
"source": "/api/mock2/options/level2?a=${a}",
"description": "切换<code>选项1</code>的值,会触发<code>选项2</code>的<code>source</code> 接口重新拉取"
}
],
"actions": []
}
```
上面例子我们实现了这个逻辑:每次选择`选项1`的时候,会触发`选项2`的`source`配置的接口重新请求,并返回不同的下拉选项。
是如何做到的?
实际上,所有**初始化接口链接上使用数据映射获取参数的形式**时,例如下面的`query=${query}`,在当前数据域中,**所引用的变量值(即 query)发生变化时**,自动重新请求该接口。
```json
{
"initApi": "/api/initData?query=${query}"
}
```
> **tip:**
>
> 触发所引用变量值发生变化的方式有以下几种:
>
> 1. 通过对表单项的修改,可以更改表单项`name`属性值所配置变量的值;
> 2. 通过[组件间联动](./linkage#%E7%BB%84%E4%BB%B6%E9%97%B4%E8%81%94%E5%8A%A8),将其他组件的值发送到目标组件,进行数据域的更新,从而触发联动效果
>
> 接口联动一般只适用于初始化接口,例如:
>
> - `form`组件中的`initApi`;
> - `select`组件中的`source`选项源接口`url`, `data`只能用于主动联动;
> - `service`组件中的`api`和`schemaApi`;
> - `crud`组件中的`api`;(crud 默认是跟地址栏联动,如果要做请关闭同步地址栏 syncLocation: false)
> - 等等...
> 如果 api 地址中有变量,比如 `/api/mock2/sample/${id}`,amis 就不会自动加上分页参数,需要自己加上,改成 `/api/mock2/sample/${id}?page=${page}&perPage=${perPage}`
#### 配置请求条件
默认在变量变化时,总是会去请求联动的接口,你也可以配置请求条件,当只有当前数据域中某个值符合特定条件才去请求该接口。
```schema: scope="body"
{
"title": "",
"type": "form",
"mode": "horizontal",
"body": [
{
"label": "选项1",
"type": "radios",
"name": "a",
"inline": true,
"options": [
{
"label": "选项A",
"value": 1
},
{
"label": "选项B",
"value": 2
},
{
"label": "选项C",
"value": 3
}
]
},
{
"label": "选项2",
"type": "select",
"size": "sm",
"name": "b",
"source": {
"method": "get",
"url": "/api/mock2/options/level2?a=${a}",
"sendOn": "this.a === 2"
},
"description": "只有<code>选项1</code>选择<code>B</code>的时候,才触发<code>选项2</code>的<code>source</code>接口重新拉取"
}
],
"actions": []
}
```
更多用法,见:[Api-配置请求条件](../types/api#%E9%85%8D%E7%BD%AE%E8%AF%B7%E6%B1%82%E6%9D%A1%E4%BB%B6)
#### 主动触发
上面示例有个问题,就是数据一旦变化就会出发重新拉取,而输入框的频繁变化值会导致频繁的拉取?没关系,也可以配置主动拉取如:
```schema: scope="body"
{
"type": "form",
"name": "my_form",
"body": [
{
"type": "input-text",
"name": "keyword",
"addOn": {
"label": "搜索",
"type": "button",
"actionType": "reload",
"target": "my_form.select"
}
},
{
"type": "select",
"name": "select",
"label": "Select",
"source": {
"method": "get",
"url": "/api/mock2/form/getOptions?waitSeconds=1",
"data": {
"a": "${keyword}"
}
}
}
]
}
```
1. 通过`api`对象形式,将获取变量值配置到`data`请求体中。
2. 配置搜索按钮,并配置该行为是刷新目标组件,并配置目标组件`target`
3. 这样我们只有在点击搜索按钮的时候,才会将`keyword`值发送给`select`组件,重新拉取选项
### 表单提交返回数据
表单提交后会将返回结果合并到当前表单数据域,因此可以基于它实现提交按钮后显示结果,比如
```schema: scope="body"
{
"type": "form",
"api": "/api/mock2/form/saveForm",
"title": "查询用户 ID",
"body": [
{
"type": "input-group",
"name": "input-group",
"body": [
{
"type": "input-text",
"name": "name",
"label": "姓名"
},
{
"type": "submit",
"label": "查询",
"level": "primary"
}
]
},
{
"type": "static",
"name": "id",
"visibleOn": "typeof data.id !== 'undefined'",
"label": "返回 ID"
}
],
"actions": []
}
```
上面的例子首先用 `"actions": []` 将表单默认的提交按钮去掉,然后在 `input-group` 里放一个 `submit` 类型的按钮来替代表单查询。
这个查询结果返回类似如下的数据
```json
{
"status": 0,
"msg": "保存成功",
"data": {
"id": 1
}
}
```
amis 会将返回的 `data` 写入表单数据域,因此下面的 `static` 组件就能显示了。
### 其他联动
还有一些组件特有的联动效果,例如 form 的 disabledOn,crud 中的 itemDraggableOn 等等,可以参考相应的组件文档。
## 组件间联动
联动很可能会出现跨组件的形式,思考下面这种场景:
有一个表单`form`组件,还有一个列表组件`crud`,我们想要把`form`提交的数据,可以用作`crud`的查询条件,并请求`crud`的接口,由于`form`和`crud`位于同一层级,因此没法使用数据链的方式进行取值。
```schema: scope="body"
[
{
"title": "查询条件",
"type": "form",
"body": [
{
"type": "input-text",
"name": "keywords",
"label": "关键字:"
}
],
"submitText": "搜索"
},
{
"type": "crud",
"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"
}
]
}
]
```
现在更改配置如下:
```schema: scope="body"
[
{
"title": "查询条件",
"type": "form",
"target": "my_crud",
"body": [
{
"type": "input-text",
"name": "keywords",
"label": "关键字:"
}
],
"submitText": "搜索"
},
{
"type": "crud",
"name": "my_crud",
"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"
}
]
}
]
```
我们进行两个调整:
1. 为`crud`组件设置了`name`属性为`my_crud`
2. 为`form`组件配置了`target`属性为`crud`的`name`:`my_crud`
更改配置后,提交表单时,amis 会寻找`target`所配置的目标组件,把`form`中所提交的数据,发送给该目标组件中,并将该数据**合并**到目标组件的数据域中,并触发目标组件的刷新操作,对于 CRUD 组件来说,刷新即重新拉取数据接口。
> 当然,`crud`组件内置已经支持此功能,你只需要配置`crud`中的`filter`属性,就可以实现上面的效果,更多内容查看 [crud -> filter](../../components/crud) 文档。
我们再来一个例子,这次我们实现 [两个 form 之间的联动](../../components/form/index#%E5%B0%86%E6%95%B0%E6%8D%AE%E5%9F%9F%E5%8F%91%E9%80%81%E7%BB%99%E7%9B%AE%E6%A0%87%E7%BB%84%E4%BB%B6)
### 发送指定数据
`target`属性支持通过配置参数来发送指定数据,例如:`"target" :"xxx?a=${a}&b=${b}"`,这样就会把当前数据域中的`a`变量和`b`变量发送给目标组件
```schema: scope="body"
[
{
"type": "form",
"title": "form1",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "Name",
"type": "input-text",
"name": "name"
},
{
"label": "Email",
"type": "input-text",
"name": "email"
},
{
"label": "Company",
"type": "input-text",
"name": "company"
}
],
"actions": [
{
"type": "action",
"actionType": "reload",
"label": "发送到 form2",
"target": "form2?name=${name}&email=${email}"
}
]
},
{
"type": "form",
"title": "form2",
"name": "form2",
"mode": "horizontal",
"api": "/api/mock2/form/saveForm",
"body": [
{
"label": "MyName",
"type": "input-text",
"name": "name"
},
{
"label": "MyEmail",
"type": "input-text",
"name": "email"
},
{
"label": "Company",
"type": "input-text",
"name": "company"
}
]
}
]
```
上例中我们给按钮上配置了`"target": "form2?name=${name}&email=${email}"`,可以把当前数据链中的`name`变量和`email`变量发送给`form2`
### 配置多个目标
`target`支持配置多个目标组件 name,用逗号隔开,例如:
```json
{
"type": "action",
"actionType": "reload",
"label": "刷新目标组件",
"target": "target1,target2"
}
```
上例中点击按钮会刷新`target1`和`target2`组件。
事实上,**组件间联动也可以实现上述任意的 [基本联动效果](./linkage#%E5%9F%BA%E6%9C%AC%E8%81%94%E5%8A%A8)(显隐联动、接口联动等其他联动)。**
### 动态目标
> 2.9.0 及以上版本
刷新目标支持表达式,比如目标可以配置成 `form-${ xxx ? '1' : '2'}`。
```schema: scope="body"
[
{
"title": "查询条件",
"type": "form",
"target": "my_crud_${searchTarget}",
"body": [
{
"type": "radios",
"name": "searchTarget",
"label": "选择目标",
value: 1,
options: [
{
value: 1,
label: "列表 1"
},
{
value: 2,
label: "列表 2"
}
],
},
{
"type": "input-text",
"name": "keywords",
"label": "关键字:"
}
],
"submitText": "搜索"
},
{
"type": "crud",
"api": "/api/mock2/sample",
"name": "my_crud_1",
"title": "列表 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"
}
]
},
{
"type": "crud",
"api": "/api/mock2/sample",
"name": "my_crud_2",
"title": "列表 2",
"columns": [
{
"name": "id",
"label": "ID"
},
{
"name": "engine",
"label": "Rendering engine"
},
{
"name": "browser",
"label": "Browser"
},
{
"name": "platform",
"label": "Platform(s)"
},
{
"name": "version",
"label": "Engine version"
}
]
}
]
```
如果目标组件在列表中,则实际渲染的时候会存在多份,通过某个固定名字没办法找到对应的组件。比如某个 crud 里面,某列设置的是一个 service,通过 service 拉取数据。如果想在操作栏里面某个操作完后刷新对应的 service,通过固定的名字是没办法找到对应的 service 的。所以名字 `name` 也支持动态名字。如: `my-service-${id}` 把行数据中动态的 id 设置进去。
```schema: scope="body"
{
type: 'crud',
api: "/api/mock2/sample",
columns: [
{
name: 'id',
label: 'ID'
},
{
type: 'service',
api: "/api/mock2/sample/${id}",
label: 'Service',
name: "my-servce-${id}",
body: [
{
type: "tpl",
tpl: "${browser}"
}
]
},
{
type: 'operation',
label: '操作',
buttons: [
{
type: "button",
label: "编辑",
actionType: "dialog",
dialog: {
"title": "编辑",
body: [
{
type: 'form',
api: "/api/mock2/sample/${id}",
body: [
{
type: 'input-text',
name: 'browser',
label: 'Browser'
}
]
}
]
},
reload: "my-servce-${id}"
}
]
}
]
}
```
> 这个例子 api 是 mock 的,所以修改后刷新没效果。

270
docs/zh-CN/concepts/schema.md Executable file
View File

@@ -0,0 +1,270 @@
---
title: 配置与组件
description: 配置与组件
type: 0
group: 💡 概念
menuName: 配置与组件
icon:
order: 9
---
## 最简单的 amis 配置
一个最简单的 amis 配置看起来是这样的:
```json
{
"type": "page",
"body": "Hello World!"
}
```
请观察上面的代码,这是一段 JSON,它的含义是:
1. `type` 是 amis 节点中最重要的字段,它告诉 amis 当前节点需要渲染的是`Page`组件。
2. 而 `body` 字段会作为 `Page` 组件的属性,`Page` 组件根据这个值来渲染页面内容。
这段配置的效果如下所示:
```schema
{
"type": "page",
"body": "Hello World!"
}
```
上面这个配置是可以**实时修改预览**的,尝试改一下 `Hello World!` 的值。
> 不过这个实时预览功能对于某些属性不生效,如果发现不符合预期,需要复制 JSON,打开另一个页面后粘贴。
## 组件
上面提到,`type`字段会告诉 amis 当前节点渲染的组件为`Page`,组件节点的配置永远都是由 **`type`字段** (用于标识当前是哪个组件)和 **属性** 构成的。
```
{
"type": "xxx",
...其它属性
}
```
## 组件树
这次我们看一个稍微复杂一点的配置:
```json
{
"type": "page",
"body": {
"type": "tpl",
"tpl": "Hello World!"
}
}
```
该配置渲染页面如下:
```schema
{
"type": "page",
"body": {
"type": "tpl",
"tpl": "Hello World!"
}
}
```
最终效果和前面的示例一样,但这次 `Page` 组件的 `body` 属性值配置了一个对象,**通过`type`指明`body`内容区内会渲染一个叫`Tpl`的组件**,它是一个模板渲染组件。
在 `body` 中除了配置对象,还可以是数组,比如下面的例子:
```schema: scope="body"
[
{
"type": "tpl",
"tpl": "Hello World!"
},
{
"type": "divider"
},
{
"type": "form",
"body": [
{
"type": "input-text",
"name": "name",
"label": "姓名"
}
]
}
]
```
可以看到通过数组的形式,增加了 `divider` 和 `form` 组件。
除了 `Page` 之外,还有很多**容器型**的组件都有 `body` 属性,通过这种树形结构,amis 就能实现复杂页面制作。
> **注意:**
>
> `Page`是 amis 页面配置中 **必须也是唯一的顶级节点**
### 通过树形来实现布局
下面这个页面就是通过树形组合出来的,大体结构是这样:
```
Page
├── Toolbar
│ └─ Form 顶部表单项
├── Grid // 用于水平布局
│ ├─ Panel
│ │ └─ Tabs
│ │ └─ Chart
│ └─ Panel
│ └─ Chart
└── CRUD
```
```schema
{
"type": "page",
"toolbar": [{
"type": "form",
"panelClassName": "mb-0",
"title": "",
"body": [{
"type": "select",
"label": "区域",
"name": "businessLineId",
"selectFirst": true,
"mode": "inline",
"options": ["北京", "上海"],
"checkAll": false
}, {
"label": "时间范围",
"type": "input-date-range",
"name": "dateRange",
"inline": true,
"value": "-1month,+0month",
"inputFormat": "YYYY-MM-DD",
"format": "YYYY-MM-DD",
"closeOnSelect": true,
"clearable": false
}],
"actions": [],
"mode": "inline",
"target": "mainPage",
"submitOnChange": true,
"submitOnInit": true
}],
"body": [{
"type": "grid",
"columns": [
{
"type": "panel",
"className": "h-full",
"body": {
"type": "tabs",
"tabs": [{
"title": "消费趋势",
"tab": [{
"type": "chart",
"config": {
"title": {
"text": "消费趋势"
},
"tooltip": {},
"xAxis": {
"type": "category",
"boundaryGap": false,
"data": ["一月", "二月", "三月", "四月", "五月", "六月"]
},
"yAxis": {},
"series": [{
"name": "销量",
"type": "line",
"areaStyle": {
"color": {
"type": "linear",
"x": 0,
"y": 0,
"x2": 0,
"y2": 1,
"colorStops": [{
"offset": 0,
"color": "rgba(84, 112, 197, 1)"
}, {
"offset": 1,
"color": "rgba(84, 112, 197, 0)"
}],
"global": false
}
},
"data": [5, 20, 36, 10, 10, 20]
}]
}
}]
}, {
"title": "账户余额",
"tab": "0"
}]
}
}, {
"type": "panel",
"className": "h-full",
"body": [{
"type": "chart",
"config": {
"title": {
"text": "使用资源占比"
},
"series": [{
"type": "pie",
"data": [{
"name": "BOS",
"value": 70
}, {
"name": "CDN",
"value": 68
}, {
"name": "BCC",
"value": 48
}, {
"name": "DCC",
"value": 40
}, {
"name": "RDS",
"value": 32
}]
}]
}
}]
}]
}, {
"type": "crud",
"className": "m-t-sm",
"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"
}]
}]
}
```
> amis 后续将会实现新的布局模式,将更容易实现复杂布局效果

1015
docs/zh-CN/concepts/style.md Executable file

File diff suppressed because it is too large Load Diff

145
docs/zh-CN/concepts/template.md Executable file
View File

@@ -0,0 +1,145 @@
---
title: 模板
description:
type: 0
group: 💡 概念
menuName: 模板
icon:
order: 11
---
为了可以更加灵活渲染文本、数据结构,amis 借鉴其他模板引擎,实现了一套模板渲染功能。
## 模板字符串
### 普通文本
配置一段普通文本并输出
```schema
{
"type": "page",
"body": "Hello World!" // 输出 Hello World!
}
```
### 文本中获取变量
可以支持在普通文本中,使用**数据映射**语法:`${xxx}` 获取数据域中变量的值,如下
```schema
{
"data": {
"text": "World!"
},
"type": "page",
"body": "Hello ${text}" // 输出 Hello World!
}
```
更多`${xxx}`语法相关介绍,移步 [数据映射](./data-mapping)。
### 渲染 html
使用**数据映射**语法:`${xxx}` 获取数据域中变量的值,并渲染 HTML
```schema
{
"data": {
"text": "World!"
},
"type": "page",
"body": "<h1>Hello</h1> <span>${text}</span>"
}
```
如果是变量本身有 html,则需要使用 raw 过滤
```schema
{
"data": {
"text": "<b>World!</b>"
},
"type": "page",
"body": "<h1>Hello</h1> <span>${text|raw}</span>"
}
```
### 表达式
> 1.5.0 及以上版本
支持简单的表达式运算以及公式调用,具体请查看[新表达式语法](./expression#新表达式语法)
```json
{
"type": "tpl",
"tpl": "${xxx == 1 ? 'One' : 'Others'}"
}
```
## JavaScript 模板引擎
amis 还支持用 JavaScript 模板引擎进行组织输出,内部采用 [lodash template](https://lodash.com/docs/4.17.15#template) 进行实现。
```schema
{
"type": "page",
"data": {
"user": "no one",
"items": [
"A",
"B",
"C"
]
},
"body": [
{
"type": "tpl",
"tpl": "User: <%- data.user %>"
},
{
"type": "divider"
},
{
"type": "tpl",
"tpl": "<% if (data.items && data.items.length) { %>Array: <% data.items.forEach(function(item) { %> <span class='label label-default'><%- item %></span> <% });} %>"
}
]
}
```
> 注意到了吗?
>
> 在 JavaScript 模板引擎中,我们获取数据域变量的方式是`data.xxx`,而不是之前的`${xxx}`,如果你熟悉 JavaScript 的话,这里模板引擎其实是将数据域,当做当前代码的数据作用域进行执行,因此需要使用`data.xxx`进行取值
>
> 要注意使用模板的时候在不同的场景下要使用正确的取值方式。
仔细看示例不难发现,语法跟 ejs 很像,`<% 这里面是 js 语句 %>`,所以只要会写 js,做页面渲染没有什么问题。另外以下是一些可用 js 方法。
- `formatDate(value, format='LLL', inputFormat='')`格式化时间格式,关于 format 请前往 [moment](https://momentjs.com/docs/) 文档页面。
- `formatTimeStamp(value, format='LLL')` 格式化时间戳为字符串。
- `formatNumber(number)` 格式化数字格式,加上千分位。
- `countDown(value)` 倒计时,显示离指定时间还剩下多少天,只支持时间戳。
下面 filters 中的方法也可以使用如: `<%- date(data.xxx, 'YYYY-MM-DD') %>`
## 注意事项
#### 1. 模板字符串 和 Javascript 模板引擎 不可以交叉使用
例如:
```json
{
"type": "tpl",
"tpl": "${data.xxx === 'a'}" //错误!
}
```
```json
{
"type": "tpl",
"tpl": "${xxx === 'a'}" // 正确
}
```