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

215
docs/zh-CN/extend/addon.md Normal file
View 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`。

View 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,官方团队会在一个工作日左右回复。

View 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` 页面跳转。

View 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};
}
});
});
```

View 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
View 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]} />;
```
![editor-plugin](../../../examples/static/editor-plugin.png)
## 工作原理
编辑器在渲染 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>
}
})
}
```
![editor-panel](../../../examples/static/editor-panel.png)
通常右侧面板都是表单配置,使用 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: []
}
]
}
];
```
![editor-panel2](../../../examples/static/editor-panel2.png)
`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'
}
]
};
```
![editor-scaffold-form](../../../examples/static/editor-scaffold-form.png)
可用配置
- `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 {
// ...
}
```
![editor-resize](../../../examples/static/editor-resize.png)
## 如何开启快速配置
![editor-inline-edit](../../../examples/static/editor-inline-edit.png)
直接配置 `popOverBody` 即可
```tsx
popOverBody = [
{
name: 'target',
label: 'Target',
type: 'input-text'
}
];
```
## MiniEditor
除了暴露 `Editor` 外,还有一个简单的编辑器 `MiniEditor`。与 `Editor` 的区别主要是,`MiniEditor` 只有编辑器区,没有左右两侧面板,像爱速搭的模型页面设计器就是基于此实现的。

179
docs/zh-CN/extend/i18n.md Normal file
View 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': '送信'
});
```

View 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 信息去组件池里面找到对应的渲染器,然后交给对应组件去完成渲染。

View 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 配置

View 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以上版本支持。

View 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>
```