vendor: amis 6.13.0 base (fork root)
This commit is contained in:
215
docs/zh-CN/extend/addon.md
Normal file
215
docs/zh-CN/extend/addon.md
Normal file
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: 扩展现有组件
|
||||
---
|
||||
|
||||
除了新增组件,在 amis 中还能扩展和修改现有组件。
|
||||
|
||||
## 扩展表单验证
|
||||
|
||||
如果默认的表单检测规则不满足需求,还可以通过代码的方式扩展。
|
||||
|
||||
### 普通用法
|
||||
|
||||
JSSDK 中的用法:
|
||||
|
||||
```javascript
|
||||
let amisLib = amisRequire('amis');
|
||||
amisLib.addRule(
|
||||
// 校验名
|
||||
'isZXS',
|
||||
// 校验函数,values 是表单里所有表单项的值,可用于做联合校验;value 是当前表单项的值
|
||||
(values, value) => {
|
||||
if (
|
||||
value === '北京' ||
|
||||
value === '上海' ||
|
||||
value === '天津' ||
|
||||
value === '重庆'
|
||||
) {
|
||||
// return true 表示校验通过
|
||||
return true;
|
||||
}
|
||||
// return false 表示校验不通过,会进行错误提示
|
||||
return false;
|
||||
},
|
||||
// 出错时的报错信息
|
||||
'输入的不是直辖市'
|
||||
);
|
||||
```
|
||||
|
||||
这样在配置中就能使用下面的验证方法
|
||||
|
||||
```
|
||||
"validations": {
|
||||
"isZXS": true
|
||||
}
|
||||
```
|
||||
|
||||
在 React 的使用方法是类似的
|
||||
|
||||
```javascript
|
||||
import {addRule} from 'amis';
|
||||
```
|
||||
|
||||
### 更加灵活的提示错误
|
||||
|
||||
> `2.9.1` 及以上版本
|
||||
|
||||
如果想在一个验证函数里根据不同情况提示不同的错误信息,需要返回固定格式的结果:
|
||||
|
||||
```js
|
||||
{
|
||||
error: true,
|
||||
msg: '错误信息'
|
||||
}
|
||||
```
|
||||
|
||||
注意,当返回对象时,`error`必须为`true` 才会判定为错误:
|
||||
|
||||
具体用法如下:
|
||||
|
||||
```javascript
|
||||
let amisLib = amisRequire('amis');
|
||||
amisLib.addRule(
|
||||
// 校验名
|
||||
'isZXS',
|
||||
// 校验函数,values 是表单里所有表单项的值,可用于做联合校验;value 是当前表单项的值
|
||||
(values, value) => {
|
||||
if (value === '新加坡') {
|
||||
// 校验不通过,提示:该地区不在国内
|
||||
return {
|
||||
error: true,
|
||||
msg: '该地区不在国内'
|
||||
};
|
||||
}
|
||||
|
||||
if (
|
||||
value === '北京' ||
|
||||
value === '上海' ||
|
||||
value === '天津' ||
|
||||
value === '重庆'
|
||||
) {
|
||||
// return true 表示校验通过
|
||||
return true;
|
||||
}
|
||||
|
||||
// 校验不通过,提示:输入的不是直辖市
|
||||
return {
|
||||
error: true,
|
||||
msg: '输入的不是直辖市'
|
||||
};
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## 同时支持多种类型编辑
|
||||
|
||||
在表单编辑中,每个 name 一般对应一种类型,如果这个 name 有多种类型,比如下面的例子中 id 的值有可能是字符串,也有可能是数字,但 type 只能设置为一种类型,这种情况如何处理?
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"mode": "horizontal",
|
||||
"body": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "input-text",
|
||||
"label": "id"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
有两种方式:
|
||||
|
||||
### 使用另一个名称作为状态
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"mode": "horizontal",
|
||||
"body": [
|
||||
{
|
||||
"name": "idIsNumber",
|
||||
"type": "switch",
|
||||
"label": "id 是数字类型"
|
||||
},
|
||||
{
|
||||
"name": "id",
|
||||
"type": "input-text",
|
||||
"label": "id",
|
||||
"hiddenOn": "data.idIsNumber"
|
||||
},
|
||||
{
|
||||
"name": "id",
|
||||
"type": "input-number",
|
||||
"label": "id",
|
||||
"visibleOn": "data.idIsNumber"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可以看到在一个 form 中可以有两个 name 相同的组件,通过 hiddenOn 或 visibleOn 来控制同时只显示一个。
|
||||
|
||||
### 使用 PipeIn/PipeOut 方法
|
||||
|
||||
如果不想增加一个新的 name,在 JS SDK 或 React 还有更高级的处理方法,可以增加一个 name 同样为 id 的 switch,实现 PipeIn/PipeOut 函数来进行自动识别,下面是个示例:
|
||||
|
||||
```javascript
|
||||
let amis = amisRequire('amis/embed');
|
||||
let amisScoped = amis.embed('#root', {
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
// 可以通过去掉下面的注释来测试
|
||||
// data: {
|
||||
// id: 1
|
||||
// },
|
||||
body: {
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
api: '/saveForm',
|
||||
body: [
|
||||
{
|
||||
type: 'switch',
|
||||
label: 'id 是数字',
|
||||
name: 'id',
|
||||
// pipeIn 返回的应该是这个组件所需的值,比如 switch 的返回值就应该是 true 或 false
|
||||
// 这里的 value 就是初始值,如果不设置将会是 undefined
|
||||
pipeIn: (value, data) => {
|
||||
if (typeof value === 'undefined') {
|
||||
return false;
|
||||
}
|
||||
return typeof value !== 'string';
|
||||
},
|
||||
// 这里的 value 是点击 switch 之后的值,比如打开就是 true,关闭就是 false
|
||||
pipeOut: (value, oldValue, data) => {
|
||||
if (value) {
|
||||
return 1; // 切换到数字之后的默认值
|
||||
} else {
|
||||
return 'id1'; // 关闭之后的默认值
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
name: 'id',
|
||||
type: 'text',
|
||||
label: 'id',
|
||||
visibleOn:
|
||||
'typeof data.id === "undefined" || typeof data.id === "string"'
|
||||
},
|
||||
{
|
||||
name: 'id',
|
||||
type: 'number',
|
||||
label: 'id',
|
||||
visibleOn: 'typeof data.id === "number"'
|
||||
}
|
||||
]
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
不过这种写法的复杂度较高
|
||||
|
||||
## 修改组件标签
|
||||
|
||||
有些组件可以设置 `wrapperComponent`,比如 Form 下默认使用 form 标签,在浏览器中会自带回车提交功能,如果想去掉这个功能,可以将 `wrapperComponent` 设置为 `div`。
|
||||
133
docs/zh-CN/extend/contribute.md
Normal file
133
docs/zh-CN/extend/contribute.md
Normal file
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: 如何贡献代码
|
||||
---
|
||||
|
||||
如果发现 amis 有不满足的功能,除了发 issue 等官方升级之外,最快的方法就是自己实现它,本文将介绍 amis 代码的基本结构,并一步步教你如何新增功能。
|
||||
|
||||
## 准备开始
|
||||
|
||||
1. 首先,你需要对 React 有基本了解,快速看一遍[官方文档](https://zh-hans.react.dev/learn)即可。
|
||||
2. 在 github 上 fork amis 项目到自己的账号下。
|
||||
3. 创建分支 `git checkout -b feat-xxx`
|
||||
|
||||
## amis 代码结构
|
||||
|
||||
amis 主要代码在 `src` 和 `scss` 目录下,这里主要介绍 `src` 下的结构:
|
||||
|
||||
```
|
||||
.
|
||||
├── Root.tsx // amis 最外层的渲染组件
|
||||
├── RootRenderer.tsx // 用于 Root.tsx,拆分一下避免文件太大
|
||||
├── Schema.ts // 基础类型定义
|
||||
├── SchemaRenderer.tsx // amis 组件渲染的主要入口
|
||||
├── Scoped.tsx // 数据域的实现
|
||||
├── WithRootStore.tsx // 用于表单项中注入 root context
|
||||
├── WithStore.tsx // 用于表单项中的数据存储及同步
|
||||
├── compat.ts // 用于兼容旧版的配置,比如将 1.1.x 的配置转成 1.2.x
|
||||
├── components // 大部分组件的实现在这里,也有很多内部使用的公共组件,这里的组件也能被其他 React 组件使用
|
||||
├── env.tsx // 默认的 env,env 可以由外部传入,比如最常见的是 fetcher,这样就能自己接管网络请求,比如使用客户端中的网络请求方法
|
||||
├── envOverwrite.ts // 用于在移动端或不同语言环境下使用不同配置
|
||||
├── factory.tsx // amis 渲染的总入口,对外暴露的 render 方法就在这里
|
||||
├── icons // 内置的 icon
|
||||
├── index.tsx // amis 项目对外的主要入口
|
||||
├── locale // 多语言翻译,目前只有英文和德语
|
||||
├── locale.tsx // 多语言支持的实现
|
||||
├── renderers // 将组件注册到 amis 渲染器中,这里大部分组件是直接引用 components 里的对应组件,也有部分简单的组件是直接在这里实现,
|
||||
├── store // mst 存储
|
||||
├── theme.tsx // 主题相关的实现
|
||||
├── themes // 主题配置,有些主题效果不太好通过 css 实现,就放这了
|
||||
├── types.ts // 一些公共的类型定义
|
||||
└── utils // amis 内部用的常用工具方法
|
||||
```
|
||||
|
||||
虽然文件很多,但对于组件开发而言,大部分情况下只需要关注 `components` 及 `renderers` 目录下的内容就行,如果发现某个组件不满足需求,可以先在 `renderers` 中找到这个组件,对齐进行修改就行。
|
||||
|
||||
下面我们将以一个实际例子来介绍如何新增一个组件。
|
||||
|
||||
## 实战:avatar 组件
|
||||
|
||||
本文的目标是新增 avatar 头像组件,完整演示如何在 amis 中添加一个新组件,完整实现可以参考这个 [pr](https://github.com/baidu/amis/pull/1684/files),本文基于这个例子进行了简化。
|
||||
|
||||
### 编写 React 组件代码代码
|
||||
|
||||
由于这个组件并不需要被其他组件复用,所以只需要在 `renderers` 目录下实现就好,整体步骤是:
|
||||
|
||||
新增 `src/renderers/Avatar.tsx` 文件,内容如下
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import {Renderer, RendererProps} from 'amis-core';
|
||||
import {BaseSchema} from '../Schema';
|
||||
import {resolveVariable, resolveVariableAndFilter} from 'amis-core';
|
||||
|
||||
// schema 是用来给编辑器提示用的,同时也作为组件 props 的类型定义
|
||||
export interface AvatarSchema extends BaseSchema {
|
||||
// 定义类型
|
||||
type: 'avatar';
|
||||
|
||||
// 下面都是这个组件的其他属性参数,这里定义了一个 src
|
||||
src?: string;
|
||||
}
|
||||
|
||||
// 大部分组件都是直接继承 RendererProps,里面包含渲染组件所需的常用属性
|
||||
export interface AvatarProps
|
||||
extends RendererProps,
|
||||
Omit<AvatarSchema, 'type' | 'className'> {}
|
||||
|
||||
// 这个是组件的实现部分
|
||||
export class AvatarField extends React.Component<AvatarProps, object> {
|
||||
render() {
|
||||
let {className, src, classnames: cx} = this.props;
|
||||
|
||||
// 所有组件的 classname 都需要使用 cx 函数,并且以大写开头,这是为了方便支持多主题
|
||||
return (
|
||||
<div className={cx('Avatar', className)}>
|
||||
<img src={src} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// 将组件注册到 amis 渲染器中
|
||||
@Renderer({
|
||||
type: 'avatar'
|
||||
})
|
||||
export class AvatarFieldRenderer extends AvatarField {}
|
||||
```
|
||||
|
||||
上面这段代码中,最核心的就是 `AvatarField`,这就是一个 React 组件。
|
||||
|
||||
接下来还需要改两处地方:
|
||||
|
||||
- 一个是 `src/Schema.ts`,需要在 `SchemaType` 里加入刚才定义的 `avatar`。
|
||||
- 另一个是 `src/index.tsx`,增加一行 `import './renders/Avatar';`。
|
||||
|
||||
这样就在 amis 中新增了一个组件,接下来我们编写组件所需的样式。
|
||||
|
||||
### 编写 SCSS 代码
|
||||
|
||||
新组件一般都需要对应的样式,首先创建 `scss/components/_avatar.scss` 文件,内容是:
|
||||
|
||||
```css
|
||||
// 注意必须有这个 #{$ns},它是为了方便生成主题,比如在 cxd 主题下,会转成 `.cxd-Avatar`
|
||||
.#{$ns}Avatar {
|
||||
}
|
||||
```
|
||||
|
||||
然后修改 `scss/themes/_common.scss`,通过 `@import '../components/avatar';` 引入这个新文件。
|
||||
|
||||
amis 中的 css 命名使用 [SUIT](https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md) 规范,请按照这个规范编写。
|
||||
|
||||
如果样式在不同主题下有区别,则需要使用 CSS 变量,在 `scss/_properties.scss` 里定义这个变量的默认值,让后在对应的主题文件中覆盖,比如 `scss/themes/_cxd-variables.scss`。
|
||||
|
||||
### 编写文档
|
||||
|
||||
新组件还需要有对应的文档来方便其他人了解和使用,首先在 `docs/zh-CN/components/avatar.md` 中创建文件,然后在 `examples/components/Components.tsx` 里引用。
|
||||
|
||||
文档编写可以参考其他示例,需要演示这个组件的所有功能。
|
||||
|
||||
## 提交 PR
|
||||
|
||||
使用 `git push --set-upstream origin feat-xxx` 创建远程分支。
|
||||
|
||||
然后通过系统提示的 `https://github.com/xxx/amis/pull/new/feat-xxx` 链接来创建 PR,官方团队会在一个工作日左右回复。
|
||||
323
docs/zh-CN/extend/custom-react.md
Normal file
323
docs/zh-CN/extend/custom-react.md
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
title: 自定义组件 - React
|
||||
---
|
||||
|
||||
## React 临时扩展
|
||||
|
||||
amis 的配置最终会转成 React 组件来执行,所以如果只是想在某个配置中加入定制功能,可以直接在这个 JSON 配置里写 React 代码,比如下面这个例子:
|
||||
|
||||
```jsx
|
||||
{
|
||||
"type": "page",
|
||||
"title": "自定义组件示例",
|
||||
"body": {
|
||||
"type": "form",
|
||||
"body": [
|
||||
{
|
||||
"type": "input-text",
|
||||
"label": "用户名",
|
||||
"name": "usename"
|
||||
},
|
||||
{
|
||||
"name": "mycustom",
|
||||
"asFormItem": true,
|
||||
"children": ({
|
||||
value,
|
||||
onChange,
|
||||
data
|
||||
}) => (
|
||||
<div>
|
||||
<p>这个是个自定义组件</p>
|
||||
<p>当前值:{value}</p>
|
||||
<a className="btn btn-default" onClick={
|
||||
() => onChange(Math.round(Math.random() * 10000))
|
||||
}>随机修改</a>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中的 `mycustom` 就是一个临时扩展,它的 `children` 属性是一个函数,它的返回内容和 React 的 Render 方法一样,即 jsx,在这个方法里你可以写任意 JavaScript 来实现自己的定制需求,这个函数有两个参数 `value` 和 `onChange`,`value` 就是组件的值,`onChange` 方法用来改变这个值,比如上面的例子中,点击链接后就会修改 `mycustom` 为一个随机数,在提交表单的时候就变成了这个随机数,而 `data` 可以拿到其它控件的值,比如 `data.username`。
|
||||
|
||||
> 注意与 "children" 并列有个 "asFormItem" 属性,这个属性表示这个节点的渲染会自动包裹成表单项,包裹成表单项就能配置
|
||||
> "name"、"description"、"validation" 之类的跟表单项有关的配置了。包括其中的 value 和 onChange 自动会跟 name 关联等功能,跟下面 `@FormItem` 注解是一个功能。
|
||||
|
||||
与之类似的还有个 `component` 属性,这个属性可以传入 React Component,如果想用 React Hooks,请通过 `component` 传递,而不是 `children`。
|
||||
|
||||
这种扩展方式既简单又灵活,但它是写在配置中的,无法在其他地方复用,也无法在可视化编辑器里编辑,如果需要复用或在可视化编辑器中使用,请使用下面的「注册自定义类型」方式:
|
||||
|
||||
## React 注册自定义类型
|
||||
|
||||
首先需要了解「[基本原理](internal)」,了解了基本原理后,来看个简单的例子:
|
||||
|
||||
```jsx
|
||||
import * as React from 'react';
|
||||
import {Renderer} from 'amis';
|
||||
|
||||
@Renderer({
|
||||
type: 'my-renderer',
|
||||
autoVar: true // amis 1.8 之后新增的功能,自动解析出参数里的变量
|
||||
})
|
||||
class CustomRenderer extends React.Component {
|
||||
render() {
|
||||
const {tip} = this.props;
|
||||
return <div>这是自定义组件:{tip}</div>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 上面这个语法需要开启 Decorator 功能,如果不支持,可以改成如下写法
|
||||
|
||||
```javascript
|
||||
Renderer({
|
||||
type: 'my-renderer',
|
||||
autoVar: true
|
||||
})(CustomRenderer);
|
||||
```
|
||||
|
||||
有了以上这段代码后,就可以这样使用了。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "page",
|
||||
"title": "自定义组件示例",
|
||||
"body": {
|
||||
"type": "my-renderer",
|
||||
"tip": "简单示例"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
看了前面[amis 工作原理](#工作原理)应该不难理解,这里注册一个 React 组件,当节点的 type 信息是 `my-renderer` 结尾时,交给当前组件来完成渲染。
|
||||
|
||||
如果这个组件还能通过 `children` 属性添加子节点,则需要使用下面这种写法:
|
||||
|
||||
```jsx
|
||||
import * as React from 'react';
|
||||
import {Renderer} from 'amis';
|
||||
|
||||
@Renderer({
|
||||
type: 'my-renderer2'
|
||||
})
|
||||
class CustomRenderer extends React.Component {
|
||||
render() {
|
||||
const {tip, body, render} = this.props;
|
||||
return (
|
||||
<div>
|
||||
<p>这是自定义组件:{tip}</p>
|
||||
{body ? (
|
||||
<div className="container">
|
||||
{render('body', body, {
|
||||
// 这里的信息会作为 props 传递给子组件,一般情况下都不需要这个
|
||||
})}
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有了以上这段代码后,就可以这样使用了。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "page",
|
||||
"title": "自定义组件示例",
|
||||
"body": {
|
||||
"type": "my-renderer2",
|
||||
"tip": "简单示例",
|
||||
"body": {
|
||||
"type": "form",
|
||||
"body": [
|
||||
{
|
||||
"type": "input-text",
|
||||
"label": "用户名",
|
||||
"name": "usename"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
跟第一个例子不同的地方是,这里多了个 `render` 方法,这个方法就是专门用来渲染子节点的。来看下参数说明:
|
||||
|
||||
- `region` 区域名称,你有可能有多个区域可以作为容器,请不要重复。
|
||||
- `node` 子节点。
|
||||
- `props` 可选,可以通过此对象跟子节点通信等。
|
||||
|
||||
### 属性支持变量
|
||||
|
||||
> 1.8.0 及以上版本新增配置,之前版本需要调用 amis 里的 resolveVariableAndFilter 方法
|
||||
|
||||
前面的例子中组件参数都是静态的,但因为配置了 `autoVar: true`,使得所有组件参数将自动支持变量,比如下面例子中的 `tip` 在组件内拿到的将是解析后的值
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "page",
|
||||
"data": {
|
||||
"myVar": "var"
|
||||
},
|
||||
"title": "自定义组件示例",
|
||||
"body": {
|
||||
"type": "my-renderer",
|
||||
"tip": "${myVar}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 表单项的扩展
|
||||
|
||||
以上是普通渲染器的注册方式,如果是表单项,为了更简单的扩充,请使用 `FormItem` 注解,而不是 `Renderer`。 原因是如果用 `FormItem` 是不用关心:label 怎么摆,表单验证器怎么实现,如何适配表单的 3 种展现方式(水平、上下和内联模式),而只用关心:有了值后如何回显,响应用户交互设置新值。
|
||||
|
||||
```jsx
|
||||
import * as React from 'react';
|
||||
import {FormItem} from 'amis';
|
||||
|
||||
@FormItem({
|
||||
type: 'custom'
|
||||
})
|
||||
class MyFormItem extends React.Component {
|
||||
render() {
|
||||
const {value, onChange} = this.props;
|
||||
|
||||
return (
|
||||
<div>
|
||||
<p>这个是个自定义组件</p>
|
||||
<p>当前值:{value}</p>
|
||||
<a
|
||||
className="btn btn-default"
|
||||
onClick={() => onChange(Math.round(Math.random() * 10000))}
|
||||
>
|
||||
随机修改
|
||||
</a>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
有了以上这段代码后,就可以这样使用了。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "page",
|
||||
"title": "自定义组件示例",
|
||||
"body": {
|
||||
"type": "form",
|
||||
"body": [
|
||||
{
|
||||
"type": "input-text",
|
||||
"label": "用户名",
|
||||
"name": "usename"
|
||||
},
|
||||
|
||||
{
|
||||
"type": "custom",
|
||||
"label": "随机值",
|
||||
"name": "random"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 注意: 使用 FormItem 默认是严格模式,即只有必要的属性变化才会重新渲染,有可能满足不了你的需求,如果忽略性能问题,可以传入 `strictMode`: `false` 来关闭。
|
||||
|
||||
表单项开发主要关心两件事。
|
||||
|
||||
1. 呈现当前值。如以上例子,通过 `this.props.value` 判定如果勾选了则显示`已勾选`,否则显示`请勾选`。
|
||||
2. 接收用户交互,通过 `this.props.onChange` 修改表单项值。如以上例子,当用户点击按钮时,切换当前选中的值。
|
||||
|
||||
至于其他功能如:label/description 的展示、表单验证功能、表单布局(常规、左右或者内联)等等,只要是通过 FormItem 注册进去的都无需自己实现。
|
||||
|
||||
需要注意,获取或者修改的是什么值跟配置中 `type` 并列的 `name` 属性有关,也就是说直接关联某个变量,自定义中直接通过 props 下发了某个指定变量的值和修改的方法。如果你想获取其他数据,或者设置其他数据可以看下以下说明:
|
||||
|
||||
- `获取其他数据` 可以通过 `this.props.data` 查看,作用域中所有的数据都在这了。
|
||||
- `设置其他数据` 可以通过 `this.props.onBulkChange`, 比如: `this.props.onBulkChange({a: 1, b: 2})` 等于同时设置了两个值。当做数据填充的时候,这个方法很有用。
|
||||
|
||||
### 其它高级定制
|
||||
|
||||
下面是一些不太常用的 amis 扩展方式及技巧。
|
||||
|
||||
#### 自定义验证器
|
||||
|
||||
如果 amis [自带的验证](../../components/form/formitem.md)能满足需求了,则不需要关心。组件可以有自己的验证逻辑。
|
||||
|
||||
```jsx
|
||||
import * as React from 'react';
|
||||
import {FormItem} from 'amis';
|
||||
import * as cx from 'classnames';
|
||||
|
||||
@FormItem({
|
||||
type: 'custom-checkbox'
|
||||
})
|
||||
export default class CustomCheckbox extends React.Component {
|
||||
validate() {
|
||||
// 通过 this.props.value 可以知道当前值。
|
||||
|
||||
return isValid ? '' : '不合法,说明不合法原因。';
|
||||
}
|
||||
// ... 其他省略了
|
||||
}
|
||||
```
|
||||
|
||||
上面的例子只是简单说明,另外可以做`异步验证`,validate 方法可以返回一个 promise。
|
||||
|
||||
#### OptionsControl
|
||||
|
||||
如果你的表单组件性质和 amis 的 Select、Checkboxes、List 差不多,用户配置配置 source 可通过 API 拉取选项,你可以用 OptionsControl 取代 FormItem 这个注解。
|
||||
|
||||
用法是一样,功能方面主要多了以下功能。
|
||||
|
||||
- 可以配置 options,options 支持配置 visibleOn hiddenOn 等表达式
|
||||
- 可以配置 `source` 换成动态拉取 options 的功能,source 中有变量依赖会自动重新拉取。
|
||||
- 下发了这些 props,可以更方便选项。
|
||||
- `options` 不管是用户配置的静态 options 还是配置 source 拉取的,下发到组件已经是最终的选项了。
|
||||
- `selectedOptions` 数组类型,当前用户选中的选项。
|
||||
- `loading` 当前选项是否在加载
|
||||
- `onToggle` 切换一个选项的值
|
||||
- `onToggleAll` 切换所有选项的值,类似于全选。
|
||||
|
||||
#### 组件间通信
|
||||
|
||||
关于组件间通信,amis 中有个机制就是,把需要被引用的组件设置一个 name 值,然后其他组件就可以通过这个 name 与其通信,比如这个[例子](../concepts/linkage)。其实内部是依赖于内部的一个 Scoped Context。你的组件希望可以被别的组件引用,你需要把自己注册进去,默认自定义的非表单类组件并没有把自己注册进去,可以参考以下代码做添加。
|
||||
|
||||
```js
|
||||
import * as React from 'react';
|
||||
import {Renderer, ScopedContext} from 'amis';
|
||||
@Renderer({
|
||||
type: 'my-renderer'
|
||||
})
|
||||
export class CustomRenderer extends React.Component {
|
||||
static contextType = ScopedContext;
|
||||
|
||||
constructor() {
|
||||
const scoped = this.context;
|
||||
scoped.registerComponent(this);
|
||||
}
|
||||
|
||||
componentWillUnmount() {
|
||||
const scoped = this.context;
|
||||
scoped.unRegisterComponent(this);
|
||||
}
|
||||
|
||||
// 其他部分省略了。
|
||||
}
|
||||
```
|
||||
|
||||
把自己注册进去了,其他组件就能引用到了。同时,如果你想找别的组件,也同样是通过 scoped 这个 context,如: `scoped.getComponentByName("xxxName")` 这样就能拿到目标组件的实例了(前提是目标组件已经配置了 name 为 `xxxName`)。
|
||||
|
||||
#### 其他功能方法
|
||||
|
||||
自定义的渲染器 props 会下发一个非常有用的 env 对象。这个 env 有以下功能方法。
|
||||
|
||||
- `env.fetcher` 可以用来做 ajax 请求如: `this.props.env.fetcher('xxxAPi', this.props.data).then((result) => console.log(result))`
|
||||
- `env.confirm` 确认框,返回一个 promise 等待用户确认如: `this.props.env.confirm('你确定要这么做?').then((confirmed) => console.log(confirmed))`
|
||||
- `env.alert` 用 Modal 实现的弹框,个人觉得更美观。
|
||||
- `env.notify` toast 某个消息 如: `this.props.env.notify("error", "出错了")`
|
||||
- `env.jumpTo` 页面跳转。
|
||||
142
docs/zh-CN/extend/custom-sdk.md
Normal file
142
docs/zh-CN/extend/custom-sdk.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: 自定义组件 - SDK
|
||||
---
|
||||
|
||||
## 使用 custom 组件临时扩展
|
||||
|
||||
基于 custom 组件可以直接在 amis 配置实现自定义功能,它的支持面最广,是唯一支持在可视化编辑器中使用的方法。
|
||||
|
||||
使用 custom 组件类似如下写法:
|
||||
|
||||
```javascript
|
||||
{
|
||||
label: '使用 custom 组件',
|
||||
name: 'username', // 如果要放在 form 中,需要设置 name,onChange 将会设置这个值
|
||||
type: 'custom',
|
||||
// onMount 将会在组件创建时执行,默认会创建一个空 div 标签,也可以设置 inline: true 来创建 span 标签
|
||||
// dom 是 dom 节点,value 是初始数据,比如表单 name 初始拿到的数据,onChange 只有在表单下才会有
|
||||
onMount: (dom, value, onChange) => {
|
||||
const button = document.createElement('button');
|
||||
button.innerText = '点击修改姓名';
|
||||
button.onclick = event => {
|
||||
// 第二个参数是要修改的表单项名称
|
||||
onChange('new name', 'username');
|
||||
event.preventDefault();
|
||||
};
|
||||
dom.appendChild(button);
|
||||
},
|
||||
// onUpdate 将会在数据更新时被调用
|
||||
// dom 是 dom 节点、data 将包含表单所有数据,prevData 是之前表单的所有数据
|
||||
onUpdate: (dom, data, prevData) => {
|
||||
console.log('数据有变化', data);
|
||||
},
|
||||
// onUnmount 将会在组件被销毁的时候调用,用于清理资源
|
||||
onUnmount:() => {
|
||||
console.log('组件被销毁');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意上面的代码用到了 JavaScript 函数,无法转成 json 格式,但这三个函数还支持字符串形式,上面的代码可以改成如下形式,这样就能在可视化编辑器里支持自定义组件了:
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"title": "custom 组件",
|
||||
"body": [
|
||||
{
|
||||
"type": "input-text",
|
||||
"name": "username",
|
||||
"label": "姓名"
|
||||
},
|
||||
{
|
||||
"name": "username",
|
||||
"type": "custom",
|
||||
"label": "自定义组件",
|
||||
"onMount": "const button = document.createElement('button'); button.innerText = '点击修改姓名'; button.onclick = event => { onChange('new name', 'username'); event.preventDefault(); }; dom.appendChild(button);"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注意上面的例子中两个组件的 name 是一样的,这是为了方便示例,因为 amis 中的数据是双向绑定的,因此 onChange 修改自身的时候,另一个「姓名」输入框由于 name 一样,也会同步更新。
|
||||
|
||||
关于 custom 组件的更多属性请参考「[Custom 组件](../../components/custom)」。
|
||||
|
||||
## JS SDK 注册组件
|
||||
|
||||
amis 组件都是基于 React 的,所以需要使用一个简单的 React 组件来注册,可以是函数组件也可以是类组件,下面以函数组件为例,将[快速开始](../start/getting-started)中的代码替换成如下示例:
|
||||
|
||||
```javascript
|
||||
let amis = amisRequire('amis/embed');
|
||||
let amisLib = amisRequire('amis');
|
||||
let React = amisRequire('react');
|
||||
|
||||
// 自定义组件,props 中可以拿到配置中的所有参数,比如 props.label 是 'Name'
|
||||
function CustomComponent(props) {
|
||||
let dom = React.useRef(null);
|
||||
React.useEffect(function () {
|
||||
// 从这里开始写自定义代码,dom.current 就是新创建的 dom 节点
|
||||
// 可以基于这个 dom 节点对接任意 JavaScript 框架,比如 jQuery/Vue 等
|
||||
dom.current.innerHTML = 'custom';
|
||||
// 而 props 中能拿到这个
|
||||
});
|
||||
return React.createElement('div', {
|
||||
ref: dom
|
||||
});
|
||||
}
|
||||
|
||||
//注册自定义组件,请参考后续对工作原理的介绍
|
||||
amisLib.Renderer({
|
||||
test: /(^|\/)my-custom/
|
||||
})(CustomComponent);
|
||||
|
||||
let amisScoped = amis.embed('#root', {
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
body: {
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
api: '/saveForm',
|
||||
body: [
|
||||
{
|
||||
label: 'Name',
|
||||
type: 'my-custom', // 注意这个的 type 对应之前注册的 test
|
||||
name: 'custom'
|
||||
}
|
||||
]
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### 示例:引入 Element UI
|
||||
|
||||
首先在页面中加入 Element UI 所需的依赖
|
||||
|
||||
```html
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://unpkg.com/element-ui/lib/theme-chalk/index.css"
|
||||
/>
|
||||
<script src="https://unpkg.com/vue/dist/vue.js"></script>
|
||||
<script src="https://unpkg.com/element-ui/lib/index.js"></script>
|
||||
```
|
||||
|
||||
然后将前面的 `React.useEffect` 改成如下即可:
|
||||
|
||||
```javascript
|
||||
React.useEffect(function () {
|
||||
dom.current.innerHTML = `
|
||||
<el-button @click="visible = true">Button</el-button>
|
||||
<el-dialog :visible.sync="visible" title="Hello world">
|
||||
<p>Try Element</p>
|
||||
</el-dialog>
|
||||
`;
|
||||
new Vue({
|
||||
el: dom.current,
|
||||
data: function () {
|
||||
return {visible: false};
|
||||
}
|
||||
});
|
||||
});
|
||||
```
|
||||
24
docs/zh-CN/extend/debug.md
Normal file
24
docs/zh-CN/extend/debug.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: 调试工具
|
||||
---
|
||||
|
||||
> 1.6.1 及以上版本
|
||||
|
||||
amis 内置了调试工具,可以查看组件内部运行日志,方便分析问题,目前在文档右侧就有显示。
|
||||
|
||||
## 开启方法
|
||||
|
||||
默认不会开启这个功能,可以通过下面三种方式开启:
|
||||
|
||||
1. render 的 env 里设置 `enableAMISDebug`。
|
||||
1. 配置全局变量 `enableAMISDebug` 的值为 `true`,比如 `window.enableAMISDebug = true`。
|
||||
1. 在页面 URL 参数中加上 `amisDebug=1`,比如 `http://xxx.com/?amisDebug=1`。
|
||||
|
||||
开启之后,在页面右侧就会显示。
|
||||
|
||||
## 目前功能
|
||||
|
||||
目前 Debug 工具提供了两个功能:
|
||||
|
||||
1. 运行日志,主要是 api 及数据转换的日志
|
||||
2. 查看组件数据链,Debug 工具展开后,点击任意组件就能看到这个组件的数据链
|
||||
626
docs/zh-CN/extend/editor.md
Normal file
626
docs/zh-CN/extend/editor.md
Normal file
@@ -0,0 +1,626 @@
|
||||
---
|
||||
title: 可视化编辑器
|
||||
---
|
||||
|
||||
目前 amis 可视化编辑器也作为单独的 npm 包发布了出来,可以通过 npm 安装使用。
|
||||
|
||||
在线体验:https://aisuda.github.io/amis-editor-demo
|
||||
示例代码:https://github.com/aisuda/amis-editor-demo
|
||||
|
||||
## 使用
|
||||
|
||||
目前有两个 npm 包:`amis-editor` 和 `amis-editor-core`。
|
||||
|
||||
- `amis-editor-core` 包含了少量底层必要的功能实现,里面没有包含 amis 内置渲染器插件的任何实现。
|
||||
- `amis-editor` 基于 `amis-editor-core` 实现了 amis 内置的所有渲染器的可视化编辑器插件。
|
||||
|
||||
如果你没有使用 amis 内置渲染器,推荐只使用 `amis-editor-core`,否则推荐使用 `amis-editor`。这里主要介绍 `amis-editor`, `amis-editor-core` 的使用方式是一样的。
|
||||
|
||||
```
|
||||
npm i amis-editor
|
||||
```
|
||||
|
||||
通过 `npm` 安装完后,在 React 项目中这样使用:
|
||||
|
||||
```jsx
|
||||
import {Editor} from 'amis-editor';
|
||||
|
||||
|
||||
render() {
|
||||
return (
|
||||
<Editor
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## 属性说明
|
||||
|
||||
- `value: Schema` amis json 配置,比如:`{type: 'page', body: 'contents...'}`
|
||||
- `onChange: (value: Schema) => void` 当编辑器修改的时候会触发。
|
||||
- `preview?: boolean` 是否为预览模式。
|
||||
- `autoFocus?: boolean` 是否自动聚焦第一个可编辑的组件。
|
||||
- `isMobile?: boolean` 是否为移动端模式,当为移动模式时,将采用 iframe 来预览。
|
||||
- `$schemaUrl?: string` 提供 amis 产出的 schema.json 的访问路径。主要用来给代码编辑模式提供属性提示信息。
|
||||
- `className?: string` 额外加个 css 类名,辅助样式定义。
|
||||
- `schemas?: JSONSchemaObject` 用来定义有哪些全局变量,辅助编辑器格式化绑定全局数据。
|
||||
- `theme?: string` amis 主题
|
||||
- `schemaFilter?: (schema: any, isPreview?: boolean) => any` 配置过滤器。可以用来实现 api proxy,比如原始配置中请求地址是 `http://baidu.com` 如果直接给编辑器预览请求,很可能会报跨域,可以自动转成 `/api/proxy?_url=xxxx`,走 proxy 解决。
|
||||
- `amisEnv?: any` 这是是给 amis 的 Env 对象,具体请前往 [env 说明](../start/getting-started#env)
|
||||
- `disableBultinPlugin?: boolean` 是否禁用内置插件
|
||||
- `disablePluginList?: Array<string> | (id: string, plugin: PluginClass) => boolean` 禁用插件列表
|
||||
- `plugins?: Array<PluginClass>` 额外的自定义插件,具体看下面的说明。
|
||||
- `isHiddenProps?: (key: string) => boolean` 是否为隐藏属性,隐藏属性是在配置中有,但是在代码编辑器中不可见。
|
||||
- `actionOptions?: any` 事件动作面板相关配置
|
||||
- `onInit?: ( event: PluginEvent<EventContext & {data: EditorManager;}>) => void` 初始化事件
|
||||
- `onActive?: (event: PluginEvent<ActiveEventContext>) => void` 点选事件
|
||||
- `beforeInsert?: (event: PluginEvent<InsertEventContext>) => false | void` 插入节点前事件
|
||||
- `afterInsert?: (event: PluginEvent<InsertEventContext>) => void;` 插入节点后事件
|
||||
- `beforeUpdate?: (event: PluginEvent<ChangeEventContext>) => false | void;` 面板里面编辑修改前的事件。可通过 event.preventDefault() 阻止。
|
||||
- `afterUpdate?: (event: PluginEvent<ChangeEventContext>) => false | void;` 面板里面编辑修改后的事件。
|
||||
- `beforeReplace?: (event: PluginEvent<ReplaceEventContext>) => false | void;` 更新渲染器前的事件,或者右键粘贴配置。可通过 event.preventDefault() 阻止。
|
||||
- `afterReplace?: (event: PluginEvent<ReplaceEventContext>) => void` 更新渲染器后的事件,或者右键粘贴配置。
|
||||
- `beforeMove?: (event: PluginEvent<MoveEventContext>) => false | void` 移动节点前触发,包括上移,下移。可通过 event.preventDefault() 阻止。
|
||||
- `afterMove?: (event: PluginEvent<MoveEventContext>) => void` 移动节点后触发,包括上移,下移。
|
||||
- `beforeDelete?: (event: PluginEvent<DeleteEventContext>) => false | void` 删除前触发。可通过 event.preventDefault() 阻止。
|
||||
- `afterDelete?: (event: PluginEvent<DeleteEventContext>) => void` 删除后触发
|
||||
- `beforeResolveEditorInfo?: ( event: PluginEvent<RendererInfoResolveEventContext> ) => false | void` 收集渲染器信息前触发。可通过 event.preventDefault() 阻止,如果阻止了,则目标组件不可编辑。
|
||||
- `afterResolveEditorInfo?: ( event: PluginEvent<RendererInfoResolveEventContext> ) => void` 收集渲染器信息后触发
|
||||
- `beforeResolveJsonSchema?: ( event: PluginEvent<RendererJSONSchemaResolveEventContext> ) => false | void` 基于渲染器获取配置的 jsonSchema 信息。可通过 event.preventDefault() 阻止。
|
||||
- `afterResolveJsonSchema?: ( event: PluginEvent<RendererJSONSchemaResolveEventContext> ) => void` 基于渲染器获取配置的 jsonSchema 信息。
|
||||
- `onDndAccept?: (event: PluginEvent<DragEventContext>) => false | void` 当将组件拖入某个容器时触发,用来决定接收不接收本次拖拽。
|
||||
- `onBuildPanels?: (event: PluginEvent<BuildPanelEventContext>) => void` 构建右侧面板的事件,可以干预右侧面板的生成,可以新增面板。
|
||||
- `onBuildContextMenus?: (event: PluginEvent<ContextMenuEventContext>) => void` 构建上下文菜单的事件
|
||||
- `onBuildToolbars?: (event: PluginEvent<BaseEventContext>) => void` 构建点选框顶部 icon 按钮事件
|
||||
- `onSelectionChange?: (event: PluginEvent<SelectionEventContext>) => void` 当点选发生变化的事件
|
||||
- `onPreventClick?: ( event: PluginEvent<PreventClickEventContext> ) => false | void` 禁用内部点击事件的事件,可以用来控制是否禁用编辑态内置组件的一些点选能力。
|
||||
- `onWidthChangeStart?: ` 当渲染器标记为 `widthMutable` 时会触发宽度变动事件
|
||||
- `onHeightChangeStart?: ` 当渲染器标记为 `heightMutable` 时会触发宽度变动事件
|
||||
- `onSizeChangeStart?: ` 当渲染器同时标记为 `widthMutable` 和 `heightMutable` 时会触发变动事件
|
||||
|
||||
## 自定义插件
|
||||
|
||||
开始之前,需要先自定义一个 amis 渲染器,然后再添加编辑器插件,让这个自定义渲染器可以在编辑器中可编辑。
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
import {Renderer} from 'amis';
|
||||
|
||||
@Renderer({
|
||||
type: 'my-renderer',
|
||||
name: 'my-renderer'
|
||||
})
|
||||
export default class MyRenderer extends React.Component<MyRendererProps> {
|
||||
static defaultProps = {
|
||||
target: 'world'
|
||||
};
|
||||
|
||||
render() {
|
||||
const {target} = this.props;
|
||||
|
||||
return <p>Hello {target}!</p>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
通过以上代码,amis 配置中通过 `type` 指定为 `my-renderer` 即可启用此组件。
|
||||
|
||||
接下来添加编辑器插件,添加插件的方式有两种。
|
||||
|
||||
- registerEditorPlugin 注册全局插件。
|
||||
- 不注册,调用 <Editor> 的时候时候通过 plugins 属性传入。
|
||||
|
||||
效果都一样,重点还是怎么写个 Plugin,示例:
|
||||
|
||||
```jsx
|
||||
import {BasePlugin} from 'amis-editor';
|
||||
|
||||
export class MyRendererPlugin extends BasePlugin {
|
||||
// 这里要跟对应的渲染器名字对应上
|
||||
// 注册渲染器的时候会要求指定渲染器名字
|
||||
rendererName = 'my-renderer';
|
||||
|
||||
// 暂时只支持这个,配置后会开启代码编辑器
|
||||
$schema = '/schemas/UnkownSchema.json';
|
||||
|
||||
// 用来配置名称和描述
|
||||
name = '自定义渲染器';
|
||||
description = '这只是个示例';
|
||||
|
||||
// tag,决定会在哪个 tab 下面显示的
|
||||
tags = ['自定义', '表单项'];
|
||||
|
||||
// 图标
|
||||
icon = 'fa fa-user';
|
||||
|
||||
// 用来生成预览图的
|
||||
previewSchema = {
|
||||
type: 'my-renderer',
|
||||
target: 'demo'
|
||||
};
|
||||
|
||||
// 拖入组件里面时的初始数据
|
||||
scaffold = {
|
||||
type: 'my-renderer',
|
||||
target: '233'
|
||||
};
|
||||
|
||||
// 右侧面板相关
|
||||
panelTitle = '自定义组件';
|
||||
panelBody = [
|
||||
{
|
||||
type: 'tabs',
|
||||
tabsMode: 'line',
|
||||
className: 'm-t-n-xs',
|
||||
contentClassName: 'no-border p-l-none p-r-none',
|
||||
tabs: [
|
||||
{
|
||||
title: '常规',
|
||||
body: [
|
||||
{
|
||||
name: 'target',
|
||||
label: 'Target',
|
||||
type: 'input-text'
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
title: '外观',
|
||||
body: []
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
定义好 plugin 后,可以有两种方式启用。
|
||||
|
||||
```jsx
|
||||
// 方式 1,注册默认插件,所有编辑器实例都会自动实例话。
|
||||
import {registerEditorPlugin} from 'amis-editor';
|
||||
|
||||
registerEditorPlugin(MyRendererPlugin);
|
||||
|
||||
// 方式2,只让某些编辑器启用
|
||||
() => <Editor plugins={[MyRendererPlugin]} />;
|
||||
```
|
||||
|
||||

|
||||
|
||||
## 工作原理
|
||||
|
||||
编辑器在渲染 amis 配置的时候,会把所有的 json(配置) 节点都自动加个 `$$id` 唯一 id。然后复写了 `rendererResolver` 方法。某个节点 {type: 'xxxx'} 在找到对应 amis 组件渲染前,都会调用这个方法。
|
||||
这个方法会在渲染之前,基于 schema、渲染器信息,通过插件去收集编辑器信息,如果收集到了,会额外的通过一个 `Wrapper` 包裹。这个 `Wrapper` 主要是自动把 `$$id` 写入到 dom 的属性上`data-editor-id="$$id"`。这样鼠标点击的时候,能够根据 dom 上的标记知道是哪个 json 节点,同时根据渲染器编辑器信息,能够生成对应的配置面板,并把对应 json 的节点做配置修改。
|
||||
|
||||
有些组件是带区域的,所以除了 dom 上标记节点信息外,还需要标记区域信息。节点能够通过 `Wrapper` 自动包裹来实现,但是区域则不能,这个要去分析组件本身是怎么实现。最终目的是要通过 `RegionWrapper` 去包裹对应 JSX.Element 来完成标记。这个 `RegionWrapper` 会自动完成 dom 的标记 `data-region="xxx" data-region-host="$$id"`,这样点击到这个 dom 的时候,能知道是哪个组件的哪个区域,这样就能往里面拖入新组件。
|
||||
|
||||
左侧的组件列表主要是将收集到的渲染器编辑器信息做个汇总展示,可拖入到指定区域内。
|
||||
|
||||
## 注册渲染器信息
|
||||
|
||||
如果想要渲染器在编辑器里面可点选,必须有插件提供这个渲染器的信息,这样才会被 `Wrapper` 包裹,才会在对应的 dom 上带上标记,才能点选。
|
||||
|
||||
在插件中可以通过实现 `getRendererInfo` 方法来注册渲染器信息,如果某个插件设置了 `rendererName` 和 `name` 属性,同时它继承 `BasePlugin` 的,则会自动完成注册逻辑。
|
||||
|
||||
```ts
|
||||
/**
|
||||
* 如果配置里面有 rendererName 自动返回渲染器信息。
|
||||
* @param renderer
|
||||
*/
|
||||
getRendererInfo({
|
||||
renderer,
|
||||
schema
|
||||
}: RendererInfoResolveEventContext): BasicRendererInfo | void {
|
||||
const plugin: PluginInterface = this;
|
||||
|
||||
if (
|
||||
schema.$$id &&
|
||||
plugin.name &&
|
||||
plugin.rendererName &&
|
||||
plugin.rendererName === renderer.name // renderer.name 会从 renderer.type 中取值
|
||||
) {
|
||||
let curPluginName = plugin.name;
|
||||
// 复制部分信息出去
|
||||
return {
|
||||
name: curPluginName,
|
||||
regions: plugin.regions,
|
||||
patchContainers: plugin.patchContainers,
|
||||
// wrapper: plugin.wrapper,
|
||||
vRendererConfig: plugin.vRendererConfig,
|
||||
wrapperProps: plugin.wrapperProps,
|
||||
wrapperResolve: plugin.wrapperResolve,
|
||||
filterProps: plugin.filterProps,
|
||||
$schema: plugin.$schema,
|
||||
renderRenderer: plugin.renderRenderer,
|
||||
multifactor: plugin.multifactor,
|
||||
scaffoldForm: plugin.scaffoldForm,
|
||||
disabledRendererPlugin: plugin.disabledRendererPlugin,
|
||||
isBaseComponent: plugin.isBaseComponent,
|
||||
rendererName: plugin.rendererName
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`RendererInfoResolveEventContext` 主要包含以下信息:
|
||||
|
||||
- `schema` 渲染器的配置
|
||||
- `schemaPath` 渲染器在整个配置中的路径信息
|
||||
- `renderer` 渲染器信息,即注册 amis 渲染器的时候注册的渲染器信息
|
||||
|
||||
插件中可以基于这些信息来决定要不要注册编辑器插件,如果注册了则此渲染器可在编辑器中点选。可注册的信息主要包含:
|
||||
|
||||
- `name: string` 渲染器名字,决定点选高亮框的名称显示
|
||||
- `searchKeywords?: string` 组件关键字,用来辅助组件列表搜索
|
||||
- `description?: string` 在组件列表中展示有用
|
||||
- `docLink?: string` 组件文档链接
|
||||
- `previewSchema?: any` 用来生成预览图
|
||||
- `tags ?:string | Array<string>` 分类, 决定会在哪个 tab 下面显示的
|
||||
- `scaffold ?: any` 在编辑器中拖入该组件时生成的默认配置项
|
||||
- `scaffolds ?: Array<any>` 脚手架也可以是多个,比如 Grid 组件,两栏,三栏组件都是用 grid 构建的,只是拖入时的初始配置不一样。
|
||||
- `$schema?: string` json schema 定义。如: `/schemas/UnkownSchema.json` 目前这个不支持自定义,只有内置渲染器才有这些信息。
|
||||
- `isBaseComponent?: boolean` 是否为内置渲染器,决定组建列表出现在内置 tab 下还是自定义 tab 下。
|
||||
- `disabledRendererPlugin?: boolean` 新增属性,用于判断是否出现在组件面板中,默认为 false,为 true 则不展示
|
||||
- `regions?: Array<RegionConfig>` 定义这个组件一共有哪些区域,比如页面组件包含的区域有:aside、body、toolbar 等。
|
||||
- `patchContainers?: Array<string>` 哪些容器属性需要自动转成数组的。如果不配置默认就从 regions 里面读取。
|
||||
- `overrides?: { [propName: string]: Function;}` 用来复写渲染器原型链上的方法,通常不需要这个。下面单独的篇章介绍
|
||||
- `vRendererConfig?: VRendererConfig` 虚拟渲染器的配置项,有时候需要给那些并不是渲染器的组件添加点选编辑功能。 比如: Tabs 下面的 Tab, 这个并不是个渲染器,但是需要可以点选修改内容。
|
||||
- `wrapperResolve?: (dom: HTMLElement) => HTMLElement | Array<HTMLElement>` 返回哪些 dom 节点,需要自动加上 data-editor-id 属性, 目前只有 TableCell 里面用到了,就它需要同时给某一列下所有 td 都加上那个属性。
|
||||
- `wrapperProps?: Record<string, any>` 默认下发哪些属性,如果要动态下发,请使用 filterProps, 比如,table 渲染器,默认下发 resizeable: false, 这样编辑的时候就不会出现列的宽度可调整功能。这个是运行态的功能,不应该出现在编辑态里面。
|
||||
- `filterProps?: (props: any, node: EditorNodeType) => Record<string, any>` 修改一些属性,一般用来干掉 $$id,或者渲染假数据, 这样它的孩子节点就不能直接点选编辑了,比如 Combo。
|
||||
- `renderRenderer?: (props: any, info: RendererInfo) => JSX.Element` 有些没有视图的组件,可以自己输出点内容,否则没办法点选编辑。
|
||||
- `multifactor?: boolean` 是否有多重身份?比如 CRUD 即是 CRUD 又可能是 Table,表格的列,即是表格列,也可能是其他文本框。 配置了这个后会自动添加多个 Panel 面板来编辑。
|
||||
- `scaffoldForm?: ScaffoldForm` 右键的时候是否出现重新构建,靠这个。同时首次新增此渲染器的时候会出现一个脚手架弹窗。下面会有单独内容介绍。
|
||||
|
||||
## 如何定义右侧配置面板
|
||||
|
||||
当点选某个组件的时候,编辑器内部会触发面板构建动作,每个插件都可以通过实现 `buildEditorPanel` 来插入右侧面板。
|
||||
|
||||
```tsx
|
||||
/**
|
||||
* 配置了 panelControls 自动生成配置面板
|
||||
* @param context
|
||||
* @param panels
|
||||
*/
|
||||
buildEditorPanel(
|
||||
context: BuildPanelEventContext,
|
||||
panels: Array<BasicPanelItem>
|
||||
) {
|
||||
|
||||
panels.push({
|
||||
key: 'xxxx',
|
||||
title: '设置',
|
||||
render: () => {
|
||||
return <div>面板内容</div>
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||

|
||||
|
||||
通常右侧面板都是表单配置,使用 amis 配置就可以完成。所以推荐的做法是,直接在这个插件上面定义 `panelBody` 或者 `panelBodyCreator` 即可。
|
||||
|
||||
```js
|
||||
panelBody = [
|
||||
{
|
||||
type: 'tabs',
|
||||
tabsMode: 'line',
|
||||
className: 'm-t-n-xs',
|
||||
contentClassName: 'no-border p-l-none p-r-none',
|
||||
tabs: [
|
||||
{
|
||||
title: '常规',
|
||||
body: [
|
||||
{
|
||||
name: 'target',
|
||||
label: 'Target',
|
||||
type: 'input-text'
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
title: '外观',
|
||||
body: []
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||

|
||||
|
||||
`panelBodyCreator` 相对于 `panelBody` 的区别是,可以基于一些上下文信息来构建不同的表单。比如在表单里面的按钮,和在表单外面的按钮配置项不一样。
|
||||
|
||||
```js
|
||||
panelBodyCreator = context => {
|
||||
console.log(context);
|
||||
return [
|
||||
{
|
||||
type: 'tabs',
|
||||
tabsMode: 'line',
|
||||
className: 'm-t-n-xs',
|
||||
contentClassName: 'no-border p-l-none p-r-none',
|
||||
tabs: [
|
||||
{
|
||||
title: '常规',
|
||||
body: [
|
||||
{
|
||||
name: 'target',
|
||||
label: 'Target',
|
||||
type: 'input-text'
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
title: '外观',
|
||||
body: []
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
`context` 中主要包含:
|
||||
|
||||
- `selections` 当前选中的渲染器,可能是多个
|
||||
- `node` 节点信息
|
||||
- `schema` 当前组件配置
|
||||
- `info` 注册的渲染器编辑器信息
|
||||
|
||||
## 如何扩充渲染器容器配置
|
||||
|
||||
开始之前请先阅读 [工作原理](#工作原理),如果是容器组件,还需要在对应 React 虚拟 dom 前包裹 `RegionWrapper`, 来完成 dom 标记。如果在注册编辑器信息的时候定义了 `regions` 信息,则会根据这个信息,自动完成 `RegionWrapper` 包裹。
|
||||
|
||||
这里先看简单的情况,比如 `container` 组件。它在 amis 大概是这样实现的容器功能。通过 `this.props.render('body', schema)` 来实现的容器功能。
|
||||
|
||||
```tsx
|
||||
renderBody(): JSX.Element | null {
|
||||
const {
|
||||
children,
|
||||
body,
|
||||
render,
|
||||
classnames: cx,
|
||||
bodyClassName,
|
||||
disabled
|
||||
} = this.props;
|
||||
|
||||
return (
|
||||
<div className={cx('Container-body', bodyClassName)}>
|
||||
{(render('body', body as any, {disabled}) as JSX.Element)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
在插件中像这样定义 `regions` 即可使得 `container` 有了 `body` 这个 region。
|
||||
|
||||
```ts
|
||||
regions: Array<RegionConfig> = [
|
||||
{
|
||||
key: 'body',
|
||||
label: '内容区'
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
插件内部会根据这个信息,自动在 `render('body', body as any, {disabled})` 的地方包裹个 `RegionWrapper`。这种方式主要是通过篡改 `this.props.render` 方法实现的。
|
||||
|
||||
再看个复杂点的情况如 `Form` 的 `actions` 区块输出。
|
||||
|
||||
```tsx
|
||||
renderFooter() {
|
||||
const actions = this.buildActions();
|
||||
|
||||
if (!actions || !actions.length) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const {
|
||||
store,
|
||||
render,
|
||||
classnames: cx,
|
||||
showErrorMsg,
|
||||
showLoading,
|
||||
show
|
||||
} = this.props;
|
||||
|
||||
return (
|
||||
<div className={cx('Modal-footer')}>
|
||||
{(showLoading !== false && store.loading) ||
|
||||
(showErrorMsg !== false && store.error) ? (
|
||||
<div className={cx('Dialog-info')} key="info">
|
||||
{showLoading !== false ? (
|
||||
<Spinner size="sm" key="info" show={store.loading} />
|
||||
) : null}
|
||||
{store.error && showErrorMsg !== false ? (
|
||||
<span className={cx('Dialog-error')}>{store.msg}</span>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
{actions.map((action, key) =>
|
||||
render(`action/${key}`, action, {
|
||||
data: store.formData,
|
||||
onAction: this.handleAction,
|
||||
key,
|
||||
disabled: action.disabled || store.loading || !show
|
||||
})
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
像这个区域,它应该包裹在 `.Modal-footer` 里面,没办法通过第一种方式实现。所以第二种配置方式是:
|
||||
|
||||
```ts
|
||||
regions: Array<RegionConfig> = [
|
||||
{
|
||||
key: 'actions',
|
||||
label: '按钮组',
|
||||
renderMethod: 'renderFooter',
|
||||
wrapperResolve: dom => dom
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
通过 `renderMethod` 信息,去篡改渲染器(React Component)的原型链,在这个方法里面自动包裹 `RegionWrapper`。包裹也有多种策略,有时候要包裹在外面,有时要包裹在第一个虚拟 dom 里面。
|
||||
|
||||
更多配置信息请参考以下 `RegionConfig` 信息
|
||||
|
||||
- `key: string` 简单情况,如果区域直接用的 render('region', subSchema),这种只需要配置 key 就能简单插入 Region 节点。
|
||||
- `label: string` 区域用来显示的名字。
|
||||
- `placeholder?: string` 区域占位字符,用于提示
|
||||
- `matchRegion?: (elem: JSX.Element | undefined | null, component: JSX.Element ) => boolean` 对于复杂的控件需要用到这个配置。如果配置了,则遍历 react dom 直到目标节点调换成 Region 节点,如果没有配置这个,但是又配置了 renderMethod 方法,那就直接将 renderMethod 里面返回的 react dom 直接包一层 Region
|
||||
- `renderMethod?: string` 指定要覆盖哪个方法。
|
||||
- `rendererName?: string` 通常是 hack 当前渲染器,但有时候当前渲染器其实是组合的别的渲染器。如果要篡改别的渲染器,则通过渲染器名字指定。
|
||||
- `insertPosition?: 'outter' | 'inner'` 当配置 renderMethod 的时候会自动把 Region 插入进去。 默认是 outter 模式,有时候可能需要配置成 inner, 比如 renderMethod 为 render 的时候。
|
||||
- `optional?: boolean` 是否为可选容器,如果是可选容器,不会强制自动创建成员
|
||||
- `renderMethodOverride?: (regions: Array<RegionConfig>, insertRegion: (component: JSX.Element, dom: JSX.Element, regions: Array<RegionConfig>, info: RendererInfo, manager: EditorManager) => JSX.Element ) => Function` 有时候有些包括是需要其他条件的,所以要自己写包裹逻辑。比如 Panel 里面的 renderBody
|
||||
- `wrapper?: React.ComponentType<RegionWrapperProps>` 用来指定用什么组件包裹,默认是 RegionWrapper
|
||||
- `wrapperResolve?: (dom: HTMLElement) => HTMLElement` 返回需要添加 data-region 的 dom 节点。
|
||||
- `modifyGhost?: (ghost: HTMLElement, schema?: any) => void` 当拖入到这个容器时,是否需要修改一下 ghost 结构?
|
||||
- `dndMode?: string` dnd 拖拽模式。比如 table 那种需要配置成 position-h
|
||||
- `accept?: (json: any) => boolean` 可以用来判断是否允许拖入当前节点。
|
||||
|
||||
## 如何定义编辑器脚手架
|
||||
|
||||
如果希望拖入组件的时候,弹出个配置框,基于用户不同的配置,生成不同的初始数据。则这里需要用到 `scaffoldForm` 配置。
|
||||
|
||||
```tsx
|
||||
scaffoldForm = {
|
||||
title: '标题',
|
||||
body: [
|
||||
{
|
||||
name: 'target',
|
||||
label: 'Target',
|
||||
type: 'input-text'
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||

|
||||
|
||||
可用配置
|
||||
|
||||
- `title` 脚手架框的标题
|
||||
- `body` 表单项配置,参考 amis 的 form 配置
|
||||
- `mode` 表单默认展示方式,参考 amis 的 form 配置
|
||||
- `size` 弹窗大小,参考 amis 的 dialog 配置
|
||||
- `initApi` 初始化接口
|
||||
- `api` 提交接口
|
||||
- `validate` 整体验证钩子
|
||||
- `pipeIn?: (value: any) => any` schema 配置转脚手架配置
|
||||
- `pipeOut?: (value: any) => any` 脚手架配置转 schema 配置
|
||||
- `canRebuild?: boolean` 是否允许重新构建
|
||||
|
||||
## 如何构建点选框顶部菜单
|
||||
|
||||
插件中定义 `buildEditorToolbar` 方法即可添加点选框顶部菜单
|
||||
|
||||
```tsx
|
||||
buildEditorToolbar(context: BaseEventContext, toolbars: Array<BasicToolbarItem>) {
|
||||
toolbars.push({
|
||||
iconSvg: 'left-arrow-to-left',
|
||||
tooltip: '向前插入组件',
|
||||
// level: 'special',
|
||||
placement: 'bottom',
|
||||
// placement: vertical ? 'bottom' : 'right',
|
||||
// className: vertical
|
||||
// ? 'ae-InsertBefore is-vertical'
|
||||
// : 'ae-InsertBefore',
|
||||
onClick: () =>
|
||||
this.manager.showInsertPanel(
|
||||
regionNode.region,
|
||||
regionNode.id,
|
||||
regionNode.preferTag,
|
||||
'insert',
|
||||
undefined,
|
||||
id
|
||||
)
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 如何构建上下文功能菜单
|
||||
|
||||
插件中定义 `buildEditorContextMenu` 方法即可添加上下文功能菜单
|
||||
|
||||
```tsx
|
||||
buildEditorContextMenu(
|
||||
{id, schema, region, selections}: ContextMenuEventContext,
|
||||
menus: Array<ContextMenuItem>
|
||||
) {
|
||||
menus.push({
|
||||
label: '重复一份',
|
||||
icon: 'copy-icon',
|
||||
disabled: selections.some(item => !item.node.duplicatable),
|
||||
onSelect: () => manager.duplicate(selections.map(item => item.id))
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 如何让渲染器可通过拖拽调整宽高
|
||||
|
||||
首先组件需要支持宽高设置,为了演示效果,将之前的 `my-renderer` 改成如下代码:
|
||||
|
||||
```tsx
|
||||
@Renderer({
|
||||
type: 'my-renderer',
|
||||
name: 'my-renderer'
|
||||
})
|
||||
export class MyRenderer extends React.Component {
|
||||
static defaultProps = {
|
||||
target: 'world'
|
||||
};
|
||||
|
||||
render() {
|
||||
const {target, width, height} = this.props;
|
||||
|
||||
return (
|
||||
<p style={{width: width || 'auto', height: height || 'auto'}}>
|
||||
Hello {target}!
|
||||
</p>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后[插件](https://github.com/aisuda/amis-editor-demo?tab=readme-ov-file#%E6%89%A9%E5%85%85%E8%87%AA%E5%AE%9A%E4%B9%89%E7%BC%96%E8%BE%91%E5%99%A8%E6%96%B0%E7%89%88)中修改继承类,即可完成拖拽调整宽高:
|
||||
|
||||
```tsx
|
||||
import {LayoutBasePlugin} from 'amis-editor';
|
||||
|
||||
export class MyRendererPlugin extends LayoutBasePlugin {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||

|
||||
|
||||
## 如何开启快速配置
|
||||
|
||||

|
||||
|
||||
直接配置 `popOverBody` 即可
|
||||
|
||||
```tsx
|
||||
popOverBody = [
|
||||
{
|
||||
name: 'target',
|
||||
label: 'Target',
|
||||
type: 'input-text'
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
## MiniEditor
|
||||
|
||||
除了暴露 `Editor` 外,还有一个简单的编辑器 `MiniEditor`。与 `Editor` 的区别主要是,`MiniEditor` 只有编辑器区,没有左右两侧面板,像爱速搭的模型页面设计器就是基于此实现的。
|
||||
179
docs/zh-CN/extend/i18n.md
Normal file
179
docs/zh-CN/extend/i18n.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: 多语言
|
||||
---
|
||||
|
||||
amis 中对多语言的支持有两方面:
|
||||
|
||||
1. amis 内部组件的多语言,比如日期组件中的日期
|
||||
1. JSON 配置中的多语言,比如配置中的 label 值
|
||||
|
||||
## amis 内部组件多语言
|
||||
|
||||
分为 JS SDK 和 React 两种用法。
|
||||
|
||||
### JS SDK
|
||||
|
||||
从 1.1.0 版本开始已经自带英文翻译,所以只需要在 props 里设置 locale 即可。
|
||||
|
||||
```javascript
|
||||
let amisScoped = amis.embed(
|
||||
'#root',
|
||||
{
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
body: {
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
api: '/saveForm',
|
||||
body: [
|
||||
{
|
||||
label: 'Name',
|
||||
type: 'input-text',
|
||||
name: 'name'
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
locale: 'en-US'
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
如果是其它语言,比如目前德语,需要单独引入文件
|
||||
|
||||
```
|
||||
<script src="sdk.js"></script>
|
||||
<script src="locale/de-DE.js"></script>
|
||||
<script type="text/javascript">
|
||||
(function () {
|
||||
let amis = amisRequire('amis/embed');
|
||||
// 通过替换下面这个配置来生成不同页面
|
||||
let amisJSON = {
|
||||
type: 'page',
|
||||
body: {
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
api: '/saveForm',
|
||||
body: [
|
||||
{
|
||||
label: 'Name',
|
||||
type: 'input-text',
|
||||
name: 'name'
|
||||
},
|
||||
{
|
||||
label: 'Email',
|
||||
type: 'input-email',
|
||||
name: 'email'
|
||||
}
|
||||
]
|
||||
}
|
||||
};
|
||||
let amisScoped = amis.embed('#root', amisJSON, {
|
||||
locale: 'de-DE'
|
||||
});
|
||||
})();
|
||||
</script>
|
||||
```
|
||||
|
||||
### React
|
||||
|
||||
React 版本中没有内置英文翻译,需要自己 import,使用如下方法:
|
||||
|
||||
```javascript
|
||||
import 'amis-ui/lib/locale/en-US';
|
||||
```
|
||||
|
||||
在渲染 amis 组件的时候设置 locale 为 en-US
|
||||
|
||||
```javascript
|
||||
{
|
||||
renderAmis(
|
||||
{
|
||||
type: 'page',
|
||||
title: '简单页面',
|
||||
body: '内容'
|
||||
},
|
||||
{
|
||||
locale: 'en-US'
|
||||
}
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 全局文本替换
|
||||
|
||||
> 1.5.0 及以上版本
|
||||
|
||||
amis 渲染的 env 参数可以配置全局文本替换,能基于它实现多语言替换功能
|
||||
|
||||
```javascript
|
||||
// sdk 中的写法
|
||||
let amisScoped = amis.embed(
|
||||
'#root',
|
||||
amisJSON,
|
||||
{
|
||||
// 这是 props
|
||||
},
|
||||
{
|
||||
replaceText: {
|
||||
AMIS_HOST: 'https://baidu.gitee.io/amis'
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
比如下面的例子会对 `AMIS_HOST` 进行替换
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "tpl",
|
||||
"tpl": "AMIS_HOST"
|
||||
}
|
||||
```
|
||||
|
||||
这个配置会对配置中的绝大部分字段进行替换,除了 `type, name, mode, target, reload` 这几个有特殊功能的字段。
|
||||
|
||||
可以通过配置 `replaceTextIgnoreKeys` 属性来进行修改,让其它字段也避免被替换。
|
||||
|
||||
## JSON 配置中设置多语言
|
||||
|
||||
在 JSON 配置中,也可以设置不同语言下的不同展现,比如前面设置了 `locale` 为 `en-US`,这时在任意 JSON 配置中都能使用 `en-US` 对象来覆盖这个语言下的效果,用于实现简单的替换效果。
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"body": [{
|
||||
"type": "input-text",
|
||||
"name": "name",
|
||||
"label": "姓名:",
|
||||
"en-US": {
|
||||
"label": "username: "
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
请点击上方的切换语言下拉框切换到英文,就能看到 `label` 属性被替换了,除了 `label` 以外,还可以覆盖其他任意属性,比如将 type 换成其他。
|
||||
|
||||
## 扩展内置组件的语言
|
||||
|
||||
如果想扩展其他语言,首先参考 `https://github.com/baidu/amis/blob/master/packages/amis-ui/src/locale/en-US.ts` 文件,然后参考后面的示例注册新语言,未翻译的文字都将使用中文。
|
||||
|
||||
### JS SDK 扩展方法
|
||||
|
||||
```javascript
|
||||
let amisLib = amisRequire('amis');
|
||||
amisLib.registerLocale('jp', {
|
||||
'Form.submit': '送信'
|
||||
});
|
||||
```
|
||||
|
||||
### React 扩展方法
|
||||
|
||||
```javascript
|
||||
import {registerLocale} from 'amis';
|
||||
registerLocale('jp', {
|
||||
'Form.submit': '送信'
|
||||
});
|
||||
```
|
||||
139
docs/zh-CN/extend/internal.md
Normal file
139
docs/zh-CN/extend/internal.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
title: 工作原理
|
||||
---
|
||||
|
||||
实现自定义类型需要了解 amis 的工作原理。
|
||||
|
||||
## 工作原理
|
||||
|
||||
amis 的渲染过程是将 `json` 转成对应的 React 组件。先通过 `json` 的 type 找到对应的 `Component`,然后把其他属性作为 `props` 传递过去完成渲染。
|
||||
|
||||
拿一个表单页面来说,如果用 React 组件开发一般长这样。
|
||||
|
||||
```jsx
|
||||
<Page title="页面标题" subTitle="副标题">
|
||||
<Form title="用户登录">
|
||||
<InputText name="username" label="用户名" />
|
||||
</Form>
|
||||
</Page>
|
||||
```
|
||||
|
||||
把以上配置方式换成 amis JSON, 则是:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "page",
|
||||
"title": "页面标题",
|
||||
"subTitle": "副标题",
|
||||
"body": {
|
||||
"type": "form",
|
||||
"title": "用户登录",
|
||||
"body": [
|
||||
{
|
||||
"type": "input-text",
|
||||
"name": "username",
|
||||
"label": "用户名"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其实只需要把 json 节点,根据 type 信息自动转成 React Component 即可。
|
||||
|
||||
> 原来组件注册是根据节点 path 注册,可以类型相同在不同的上下文中用不同的渲染器去渲染,后来发现这样反而增加了使用成本
|
||||
> 所以新版本直接通过 type 类型来注册组件,跟节点所在上下文无关。
|
||||
|
||||
Page 组件的示例代码
|
||||
|
||||
```jsx
|
||||
import * as React from 'react';
|
||||
import {Renderer} from 'amis-core';
|
||||
|
||||
@Renderer({
|
||||
type: 'page'
|
||||
// ... 其他信息隐藏了
|
||||
})
|
||||
export class PageRenderer extends React.Component {
|
||||
// ... 其他信息隐藏了
|
||||
render() {
|
||||
const {
|
||||
title,
|
||||
body,
|
||||
render // 用来渲染孩子节点,如果当前是叶子节点则可以忽略。
|
||||
} = this.props;
|
||||
return (
|
||||
<div className="page">
|
||||
<h1>{title}</h1>
|
||||
<div className="body-container">
|
||||
{render('body', body) /*渲染孩子节点*/}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// 如果不支持 Decorators 语法也可以使用如下写法
|
||||
export Renderer({
|
||||
type: 'page'
|
||||
})(class PageRenderer extends React.Component {
|
||||
render() {
|
||||
// ...同上
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Form 组件的示例代码
|
||||
|
||||
```jsx
|
||||
@Renderer({
|
||||
type: 'form'
|
||||
// ... 其他信息隐藏了
|
||||
})
|
||||
export class FormRenderer extends React.Component {
|
||||
// ... 其他信息隐藏了
|
||||
render() {
|
||||
const {
|
||||
title,
|
||||
body,
|
||||
render // 用来渲染孩子节点,如果当前是叶子节点则可以忽略。
|
||||
} = this.props;
|
||||
return (
|
||||
<form className="form">
|
||||
{body.map((control, index) => (
|
||||
<div className="form-item" key={index}>
|
||||
{render(`${index}/control`, control)}
|
||||
</div>
|
||||
))}
|
||||
</form>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Text 组件的示例代码
|
||||
|
||||
```jsx
|
||||
@Renderer({
|
||||
type: 'input-text'
|
||||
// ... 其他信息隐藏了
|
||||
})
|
||||
export class FormItemTextRenderer extends React.Component {
|
||||
// ... 其他信息隐藏了
|
||||
render() {
|
||||
const {
|
||||
label,
|
||||
name,
|
||||
onChange
|
||||
} = this.props;
|
||||
return (
|
||||
<div className="form-group">
|
||||
<label>{label}<label>
|
||||
<input type="text" onChange={(e) => onChange(e.currentTarget.value)} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
那么渲染过程就是根据节点 type 信息,跟组件池中的找到对应的组件实现,如果命中,则把当前节点转给对应组件渲染,节点中其他属性将作为目标组件的 props。需要注意的是,如果是容器组件,比如以上例子中的 `page` 组件,从 props 中拿到的 `body` 是一个子节点,由于节点类型是不固定,由使用者决定,所以不能直接完成渲染,所以交给属性中下发的 `render` 方法去完成渲染,`{render('body', body)}`,他的工作就是拿子节点的 type 信息去组件池里面找到对应的渲染器,然后交给对应组件去完成渲染。
|
||||
86
docs/zh-CN/extend/mobile.md
Normal file
86
docs/zh-CN/extend/mobile.md
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: 移动端展现
|
||||
---
|
||||
|
||||
## 移动端原生 UI
|
||||
|
||||
从 1.6.0 版本开始,amis 会默认在移动端下使用仿原生 UI 的展现,比如日期选择会从底部弹出。
|
||||
|
||||
由于这个仿原生 UI 是新开发的组件,有些 amis PC 版本的高级配置功能还不支持,比如 select 下的搜索过滤等,如果需要这些功能,可以先通过 props 里的 `useMobileUI` 属性关闭。
|
||||
|
||||
方法 1:全局关闭
|
||||
|
||||
```js
|
||||
amis.embed(
|
||||
'#root',
|
||||
{
|
||||
// amis schema
|
||||
},
|
||||
{
|
||||
// 这里是初始 props
|
||||
},
|
||||
{
|
||||
theme: 'antd',
|
||||
useMobileUI: false
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
方法 2:针对某个组件进行关闭
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "select",
|
||||
"useMobileUI": false
|
||||
}
|
||||
```
|
||||
|
||||
## 移动端定制配置
|
||||
|
||||
有时候我们需要在移动端下展示不同效果,可以通过 `mobile` 属性来在移动端下覆盖部分属性。
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"body": [{
|
||||
"name": "email",
|
||||
"type": "input-email",
|
||||
"label": "邮箱:",
|
||||
"mobile": {
|
||||
"name": "phone",
|
||||
"type": "text",
|
||||
"label": "电话:",
|
||||
"validations": {
|
||||
"isPhoneNumber": true
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
请点击上方切换到移动端预览效果。
|
||||
|
||||
`mobile` 属性可以出现在配置中的任意地方,替换父节点的任意属性,比如前面的例子可以写成放在 `form` 上替换所有 `body`
|
||||
|
||||
```schema: scope="body"
|
||||
{
|
||||
"type": "form",
|
||||
"body": [{
|
||||
"name": "email",
|
||||
"type": "input-email",
|
||||
"label": "邮箱:"
|
||||
}],
|
||||
"mobile": {
|
||||
"body": [{
|
||||
"name": "phone",
|
||||
"type": "input-text",
|
||||
"label": "电话:",
|
||||
"validations": {
|
||||
"isPhoneNumber": true
|
||||
}
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 注意这里对于移动端的判断是根据页面宽度,和 CSS 保持一致,所以即便是在 PC 上,如果页面宽度很小也会切换到 mobile 配置
|
||||
490
docs/zh-CN/extend/tracker.md
Normal file
490
docs/zh-CN/extend/tracker.md
Normal file
@@ -0,0 +1,490 @@
|
||||
---
|
||||
title: 页面交互行为跟踪
|
||||
---
|
||||
|
||||
从 1.5.0 版本开始,amis 内置了跟踪用户交互行为采集功能。
|
||||
|
||||
## 使用方法
|
||||
|
||||
amis 只负责采集,对行为的存储和分析都需要外部实现。
|
||||
|
||||
在 amis 渲染时的第三个参数 env 可以传递 tracker 函数,下面以 sdk 作为示例,具体实现可以根据实际需求修改,比如可以收集一段时间后再批量提交等。
|
||||
|
||||
```js
|
||||
amis.embed(
|
||||
'#root',
|
||||
{
|
||||
// amis schema
|
||||
},
|
||||
{
|
||||
// 这里是初始 props
|
||||
},
|
||||
{
|
||||
tracker: (eventTrack, props) => {
|
||||
const blob = new Blob([JSON.stringify(eventTrack)], {
|
||||
type: 'application/json'
|
||||
});
|
||||
navigator.sendBeacon('/tracker', blob);
|
||||
}
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## 参数类型
|
||||
|
||||
eventTrack 的类型定义是
|
||||
|
||||
```typescript
|
||||
interface EventTrack {
|
||||
// 后面会详细介绍
|
||||
eventType:
|
||||
| 'api'
|
||||
| 'url'
|
||||
| 'link'
|
||||
| 'dialog'
|
||||
| 'drawer'
|
||||
| 'copy'
|
||||
| 'reload'
|
||||
| 'email'
|
||||
| 'prev'
|
||||
| 'next'
|
||||
| 'cancel'
|
||||
| 'close'
|
||||
| 'submit'
|
||||
| 'confirm'
|
||||
| 'reset'
|
||||
| 'reset-and-submit'
|
||||
| 'formItemChange'
|
||||
| 'tabChange'
|
||||
| 'pageHidden'
|
||||
| 'pageVisible';
|
||||
|
||||
/**
|
||||
* 事件数据,根据不同事件有不同结构,下面会详细说明
|
||||
*/
|
||||
eventData: ActionSchema | Api;
|
||||
}
|
||||
```
|
||||
|
||||
有时候无法通过 `eventData` 区分点击行为,比如有个两个提交按钮
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "提交",
|
||||
"primary": true
|
||||
},
|
||||
{
|
||||
"label": "提交",
|
||||
"primary": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
当它触发事件的时 `EventTrack` 内容是一样的
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "submit",
|
||||
"eventData": {
|
||||
"primary": true,
|
||||
"label": "提交"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如何区分究竟是哪个事件?可以通过增加 `id` 属性,比如
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "button1",
|
||||
"label": "提交",
|
||||
"primary": true
|
||||
},
|
||||
{
|
||||
"id": "button2",
|
||||
"label": "提交",
|
||||
"primary": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
这样触发事件中就会包含 `id` 字段来方便区分,比如
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "submit",
|
||||
"eventData": {
|
||||
"id": "button1",
|
||||
"primary": true,
|
||||
"label": "提交"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
另一个方法是通过 `tracker` 的第二个参数 `props` 来判断,它可以拿到这个组件的所有属性配置
|
||||
|
||||
## 事件示例
|
||||
|
||||
除了下面的文档,还可以打开浏览器的控制台,在 `debug` 分类下可以看到实际操作时的例子
|
||||
|
||||
### api
|
||||
|
||||
api 的来源有两方面,一个是各种组件的 api 及 source 配置,另一个是 action 里的 ajax 类型请求
|
||||
|
||||
以 crud 为例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "api",
|
||||
"eventData": {
|
||||
"method": "get",
|
||||
"url": "/api/mock2/sample?page=1&perPage=10",
|
||||
"query": {
|
||||
"page": 1,
|
||||
"perPage": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果是 post 则类似下面的数据
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "api",
|
||||
"eventData": {
|
||||
"method": "post",
|
||||
"url": "/api/mock2/form/saveForm"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
为了避免信息泄露在 eventData 里没有包含提交数据,要获取提交数据详情需要通过第二个参数,参考下面的例子
|
||||
|
||||
```javascript
|
||||
{
|
||||
tracker: (eventTrack, data) => {
|
||||
console.log('提交数据详情', data);
|
||||
const blob = new Blob([JSON.stringify(eventTrack)], {
|
||||
type: 'application/json'
|
||||
});
|
||||
navigator.sendBeacon('/tracker', blob);
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### url
|
||||
|
||||
这是打开外部链接事件,注意不要和 link 混淆,link 一般用来做应用内相对地址无刷新跳转
|
||||
|
||||
示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "url",
|
||||
"eventData": {
|
||||
"url": "https://www.baidu.com",
|
||||
"blank": true,
|
||||
"label": "百度一下,你就知道"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这个事件有可能是 Link 组件触发,也有可能是 Action 组件触发,如果是 Action 这是类似下面的参数
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "url",
|
||||
"eventData": {
|
||||
"url": "http://www.baidu.com",
|
||||
"level": "success",
|
||||
"blank": true,
|
||||
"label": "打开 Baidu"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Action 组件会多些数据
|
||||
|
||||
### link
|
||||
|
||||
触发这个事件主要是 Action 和 Nav 组件
|
||||
|
||||
如果是 Action,数据将会是
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "link",
|
||||
"eventData": {
|
||||
"label": "进入介绍页",
|
||||
"level": "info",
|
||||
"link": "../index"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果是 Nav,数据将会是
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "link",
|
||||
"eventData": {
|
||||
"label": "Nav 2-2",
|
||||
"link": "?cat=2-2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
它们都有 label 及 link 字段
|
||||
|
||||
### dialog
|
||||
|
||||
这个事件主要由 action 触发,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "dialog",
|
||||
"eventData": {
|
||||
"dialog": {
|
||||
"title": "提示",
|
||||
"closeOnEsc": true,
|
||||
"body": "这是个简单的弹框"
|
||||
},
|
||||
"label": "打开弹框"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
需要注意 dialog 里会包含所有弹框的 schema 配置,可能会导致提交数据太大,建议根据需求裁剪。
|
||||
|
||||
### drawer
|
||||
|
||||
这个事件主要由 action 触发,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "drawer",
|
||||
"eventData": {
|
||||
"drawer": {
|
||||
"position": "left",
|
||||
"size": "xs",
|
||||
"title": "提示",
|
||||
"body": "这是个简单的弹框"
|
||||
},
|
||||
"label": "左侧弹出-极小框"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
和前面的 dialog 示例,它的数据中会包含所有 drawer 配置,可能会内容过大,需要根据需求过滤
|
||||
|
||||
### copy
|
||||
|
||||
由 action 触发,示例如下
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "copy",
|
||||
"eventData": {
|
||||
"content": "http://www.baidu.com",
|
||||
"label": "复制一段文本"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### reload
|
||||
|
||||
由 action 触发,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "reload",
|
||||
"eventData": {
|
||||
"label": "搜索",
|
||||
"target": "my_form.select"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### email
|
||||
|
||||
由 action 触发,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "email",
|
||||
"eventData": {
|
||||
"to": "amis@baidu.com",
|
||||
"cc": "baidu@baidu.com",
|
||||
"subject": "这是邮件主题",
|
||||
"body": "这是邮件正文",
|
||||
"label": "发送邮件"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### prev/next
|
||||
|
||||
可能有两个地方,一个是 Wizard 里的上一步下一步,还有可能是 Dialog 里的上一个下一个,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "next",
|
||||
"eventData": {
|
||||
"level": "info",
|
||||
"label": "下一个"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### cancel
|
||||
|
||||
action 里的取消事件,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "cancel",
|
||||
"eventData": {
|
||||
"label": "关闭"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### close
|
||||
|
||||
action 里的关闭事件,主要用于关闭弹框,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "close",
|
||||
"eventData": {
|
||||
"label": "算了"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### submit
|
||||
|
||||
点击提交按钮的事件,这个事件可能还会同时触发 `api` 事件,比如表单的提交按钮。
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "submit",
|
||||
"eventData": {
|
||||
"primary": true,
|
||||
"label": "提交"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### confirm
|
||||
|
||||
action 中的事件,主要用于关闭弹框
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "confirm",
|
||||
"eventData": {
|
||||
"primary": true,
|
||||
"label": "确认"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### reset
|
||||
|
||||
由 action 触发,主要用于重置表单数据,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "reset",
|
||||
"eventData": {
|
||||
"label": "重置"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### reset-and-submit
|
||||
|
||||
由 action 触发,会重置表单并提交数据
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "reset-and-submit",
|
||||
"eventData": {
|
||||
"label": "重置并提交"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### formItemChange
|
||||
|
||||
表单项数据变化时,也就是用户在表单里输入和修改任何数据时触发,比如
|
||||
|
||||
> 有一个特例是 input-password 类型的字段不会触发这个事件,避免隐私风险
|
||||
> 但在 api 中还是有可能包含隐私信息,因此建议前面 api 类的事件不记录数据提交内容
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "formItemChange",
|
||||
"eventData": {
|
||||
"name": "name",
|
||||
"label": "用户名",
|
||||
"type": "input-text",
|
||||
"value": "amis"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
事件数据里主要是 `name` `type` 和 `value`
|
||||
|
||||
需要注意这个事件非常频繁,只要修改内容就会触发。
|
||||
|
||||
和 action 类似,如果给表单项加上 `id` 字段也会透传到这里,方便用于区分同名输入框,比如
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "formItemChange",
|
||||
"eventData": {
|
||||
"id": "name1",
|
||||
"name": "name",
|
||||
"label": "用户名",
|
||||
"type": "input-text",
|
||||
"value": "amis"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### tabChange
|
||||
|
||||
tab 切换事件,示例
|
||||
|
||||
```json
|
||||
{
|
||||
"eventType": "tabChange",
|
||||
"eventData": {
|
||||
"key": "tab2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
默认情况下 `key` 的值从 `0` 开始,如果 tab 上设置了 `hash` 值就会用这个值。
|
||||
|
||||
同样,如果 tabs 设置了 id,也会输出这个 id 值方便区分
|
||||
|
||||
### pageHidden
|
||||
|
||||
当 tab 切换或者页面关闭时触发,可以当成用户离开页面的时间。
|
||||
|
||||
### pageVisible
|
||||
|
||||
当用户又切换回当前页面的时间,可以当做是用户重新访问的开始时间。
|
||||
|
||||
由于 amis 可能被嵌入到页面中,所以 amis 无法知晓页面首次打开的时间,需要自行处理。
|
||||
|
||||
### pageLoaded
|
||||
|
||||
当Page组件加载完成时触发,可用于收集页面首次打开的时间,需确保当前页面有Page组件。
|
||||
备注: 2.8.0以上版本支持。
|
||||
160
docs/zh-CN/extend/ui-library.md
Normal file
160
docs/zh-CN/extend/ui-library.md
Normal file
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: 将 amis 当成 UI 库用
|
||||
---
|
||||
|
||||
amis 不仅有纯配置的用法,还能当成 UI 库来使用,实现 90% 低代码,10% 代码开发的混合模式,在灵活性上。
|
||||
|
||||
> 需要注意以下都需要在配置中写函数,因此不再是纯粹的 JSON,所以暂时不能在可视化编辑器的「代码」模式下使用
|
||||
> 从 1.3.0 开始按钮的 onClick 支持字符串格式,因此可以在可视化编辑器中使用
|
||||
|
||||
## 事件监听
|
||||
|
||||
amis 提供了一些交互配置,但有时候这些交互无法满足需求,这时我们可以监听这些事件,然后用代码实现复杂交互需求,比如最常见的是表单事件。
|
||||
|
||||
```javascript
|
||||
let amisJSON = {
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
body: [
|
||||
{
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
onFinished: values => {
|
||||
console.log('form', values);
|
||||
return false; // 这样可以禁掉 amis 后续的默认行为
|
||||
},
|
||||
body: [
|
||||
{
|
||||
label: 'Name',
|
||||
type: 'input-text',
|
||||
name: 'name',
|
||||
onChange: value => {
|
||||
console.log('Name', value);
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'button',
|
||||
label: '按钮修改',
|
||||
onClick: (e, props) => {
|
||||
console.log('消息通知');
|
||||
props.formStore.setValues({name: 'amis'});
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
这个例子中我们监听了 3 个事件,输入框数据变化、表单提交、按钮点击,然后在这些地方使用代码实现特殊功能。
|
||||
|
||||
## 监听广播事件
|
||||
|
||||
> 3.0.0 以后引入
|
||||
|
||||
amis 从 1.7.0 版本开始支持了[事件动作](../concepts/event-action),各个组件内部也陆续补充了很多事件(可以查看每个组件文档的最底下,有事件表说明)。像这类事件也是可以监听的,分为两步来实现:第一步监听组件事件做广播动作、第二步最外层监听广播事件写业务逻辑。
|
||||
|
||||
配置 form 事件动作,当表单提交成功后,广播一个 `formSubmited` 事件。
|
||||
|
||||
```js
|
||||
let amisJSON = {
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
body: [
|
||||
{
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
onEvent: {
|
||||
submitSucc: {
|
||||
actions: [
|
||||
{
|
||||
actionType: 'broadcast',
|
||||
args: {
|
||||
eventName: 'formSubmited'
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
body: [
|
||||
{
|
||||
label: 'Name',
|
||||
type: 'input-text',
|
||||
name: 'name'
|
||||
},
|
||||
{
|
||||
type: 'submit',
|
||||
label: 'Submit'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
渲染 amis 的时候通过 `onBroadcast` 监听内部广播。
|
||||
|
||||
```tsx
|
||||
import {render as renderAmis} from 'amis';
|
||||
|
||||
function DemoComponent() {
|
||||
function handleBroadcast(type: string, rawEvent: any, data: any) {
|
||||
console.log(type);
|
||||
if (type === 'formSubmited') {
|
||||
console.log('内部表单提交了');
|
||||
}
|
||||
}
|
||||
|
||||
return <div>
|
||||
{renderAmis(amisJSON, {onBroadcast: handleBroadcast})}
|
||||
</div>
|
||||
};
|
||||
```
|
||||
|
||||
## 使用 amis 公共方法
|
||||
|
||||
amis 对外还提供了一些方法,比如弹出消息通知,可以通过 `amisRequire('amis')` 获取到这些 amis 对外提供的方法。
|
||||
|
||||
```javascript
|
||||
let amis = amisRequire('amis/embed');
|
||||
let amisLib = amisRequire('amis');
|
||||
let amisScoped = amis.embed('#root', {
|
||||
type: 'page',
|
||||
title: '表单页面',
|
||||
body: {
|
||||
type: 'form',
|
||||
mode: 'horizontal',
|
||||
api: '/saveForm',
|
||||
body: [
|
||||
{
|
||||
type: 'button',
|
||||
label: '按钮',
|
||||
onClick: () => {
|
||||
amisLib.toast.info('消息通知');
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
具体有哪些可以参考 [https://github.com/baidu/amis/blob/master/packages/amis/src/index.tsx](https://github.com/baidu/amis/blob/master/packages/amis/src/index.tsx)
|
||||
|
||||
## React 中引入 amis 的组件
|
||||
|
||||
在 React 环境下使用 amis,还可以直接引入 amis 内置组件,在 amis 项目源码 `src/components` 下的组件都是标准 React 组件,可以在项目中直接引用,这样就能将 amis 当成纯粹 UI 库来使用。
|
||||
|
||||
```jsx
|
||||
import {Button} from 'amis-ui';
|
||||
|
||||
...
|
||||
|
||||
<Button
|
||||
onClick={() => {}}
|
||||
type="button"
|
||||
level="link"
|
||||
className="navbar-btn"
|
||||
>
|
||||
按钮
|
||||
</Button>
|
||||
```
|
||||
Reference in New Issue
Block a user