* 文档优化 * 文档细节调整,删除示例的 height 设置,使用自动撑开 * sdk 使用完整例子,因为新版没发布 * 修复官网语言不正确问题 * 增加 icon 调整颜色及大小的例子 * 修复文字错误 * 补充 each 的文档 * 修复 zh-CN 大写问题
13 KiB
title | description |
---|---|
快速开始 |
amis 有两种使用方法:
SDK 版本适合对前端或 React 不了解的开发者,它不依赖 npm 及 webpack,可以像 Vue/jQuery 那样外链代码就能使用。
SDK
下载方式:
- github 的 releases,文件是 sdk.tar.gz。
- 使用
npm i amis
来下载,在node_modules\amis\sdk
目录里就能找到。
默认会提供一个 demo.html 作为示例,双击这个文件打开就能看到效果,其中最重要是如下代码:
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8" />
<title>amis demo</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=1"
/>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<link rel="stylesheet" href="sdk.css" />
<!-- 从 1.1.0 开始 sdk.css 将不支持 IE 11,如果要支持 IE11 请引用这个 css,并把前面那个删了 -->
<!-- <link rel="stylesheet" href="sdk-ie11.css" /> -->
<!-- 不过 amis 开发团队几乎没测试过 IE 11 下的效果,所以可能有细节功能用不了,如果发现请报 issue -->
<style>
html,
body,
.app-wrapper {
position: relative;
width: 100%;
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<div id="root" class="app-wrapper"></div>
<script src="sdk.js"></script>
<script type="text/javascript">
(function () {
let amis = amisRequire('amis/embed');
// 通过替换下面这个配置来生成不同页面
let amisJSON = {
type: 'page',
title: '表单页面',
body: {
type: 'form',
mode: 'horizontal',
api: '/saveForm',
controls: [
{
label: 'Name',
type: 'text',
name: 'name'
},
{
label: 'Email',
type: 'email',
name: 'email'
}
]
}
};
let amisScoped = amis.embed('#root', amisJSON);
})();
</script>
</body>
</html>
切换主题
jssdk 版本默认使用 sdk.css
即默认主题,如果你想用使用云舍,请改成引用 cxd.scss
。同时 js 渲染地方第四个参数传入 theme
属性。如:
amis.embed(
'#root',
{
// amis schema
},
{
// 这里是初始 props
},
{
theme: 'cxd'
}
);
暗黑主题同理,改成引用 'dark.css' 同时主题设置成 dark
。
控制 amis 的行为
amis.embed
函数还支持以下配置项来控制 amis 的行为,比如在 fetcher 的时候加入自己的处理逻辑,这些函数参数的说明在后面 React 中也有介绍。
let amisScoped = amis.embed(
'#root',
amisJSON,
{
// 这里是初始 props,一般不用传。
// locale: 'en' // props 中可以设置语言,默认是中文
},
{
// 可以不传,用来实现 ajax 请求
fetcher: (url, method, data, config) => {},
// 可以不传,全局 api 适配器。
// 另外在 amis 配置项中的 api 也可以配置适配器,针对某个特定接口单独处理。
responseAdpater(api, response, query, request) {
return response;
}
// 可以不传,用来接管页面跳转,比如用 location.href 或 window.open,或者自己实现 amis 配置更新
// jumpTo: to => { location.href = to; },
// 可以不传,用来实现地址栏更新
// updateLocation: (to, replace) => {},
// 可以不传,用来判断是否目标地址当前地址。
// isCurrentUrl: url => {},
// 可以不传,用来实现复制到剪切板
// copy: content => {},
// 可以不传,用来实现通知
// notify: (type, msg) => {},
// 可以不传,用来实现提示
// alert: content => {},
// 可以不传,用来实现确认框。
// confirm: content => {},
// theme: 'cxd' // 主题,默认是 default,还可以设置成 cxd 或 dark,但记得引用它们的 css,比如 sdk 目录下的 cxd.css
}
);
同时返回的 amisScoped
对象可以获取到 amis 渲染的内部信息,它有如下方法:
getComponentByName(name)
用于获取渲染出来的组件,比如下面的示例
{
"type": "page",
"name": "page1",
"title": "表单页面",
"body": {
"type": "form",
"name": "form1",
"controls": [
{
"label": "Name",
"type": "text",
"name": "name1"
}
]
}
}
可以通过 amisScoped.getComponentByName('page1.form1').getValues()
来获取到所有表单的值,需要注意 page 和 form 都需要有 name 属性。
还可以通过 amisScoped.getComponentByName('page1.form1').setValues({'name1': 'othername'})
来修改表单中的值。
react
初始项目请参考 https://github.com/fex-team/amis-react-starter。
如果在已有项目中,React 版本需要是 ^16.8.6
,mobx 需要 ^4.5.0
。
安装
npm i amis
主题样式
目前支持三种主题:default(默认主题)
、cxd(云舍)
和dark(暗黑)
- 引入样式文件:
html 中引入:
<link href="./node_modules/amis/lib/themes/default.css" />
<!-- 或 <link href="./node_modules/amis/lib/themes/cxd.css" /> -->
<!-- 或 <link href="./node_modules/amis/lib/themes/dark.css" /> -->
js 中引入:
import './node_modules/amis/lib/themes/default.css';
// 或 import './node_modules/amis/lib/themes/cxd.css';
// 或 import './node_modules/amis/lib/themes/dark.css';
上面只是示例,请根据自己的项目结构调整引用路径
- 渲染器使用配置主题
renderAmis(
{
type: 'page',
title: '简单页面',
body: '内容'
},
{
// props
},
{
// env...
theme: 'default' // cxd 或 dark
}
);
使用指南
可以在 React Component 这么使用(TypeScript)。
- 安装部分示例需要的插件库
npm i axios copy-to-clipboard
为了方便示例,上面选用了我们常用几个插件库,你完全可以选择自己喜欢的插件并重新实现
- 代码实现(React Typescript)
import * as React from 'react';
import axios from 'axios';
import copy from 'copy-to-clipboard';
import {render as renderAmis, ToastComponent, AlertComponent} from 'amis';
import {alert, confirm} from 'amis/lib/components/Alert';
import {toast} from 'amis/lib/components/Toast';
class MyComponent extends React.Component<any, any> {
render() {
return (
<div>
<p>通过 amis 渲染页面</p>
<ToastComponent key="toast" position={'top-right'} />
<AlertComponent key="alert" />
{renderAmis(
{
// 这里是 amis 的 Json 配置。
type: 'page',
title: '简单页面',
body: '内容'
},
{
// props...
// locale: 'en' // 请参考「多语言」的文档
},
{
// 下面三个接口必须实现
fetcher: ({
url, // 接口地址
method, // 请求方法 get、post、put、delete
data, // 请求数据
responseType,
config, // 其他配置
headers // 请求头
}: any) => {
config = config || {};
config.withCredentials = true;
responseType && (config.responseType = responseType);
if (config.cancelExecutor) {
config.cancelToken = new (axios as any).CancelToken(
config.cancelExecutor
);
}
config.headers = headers || {};
if (method !== 'post' && method !== 'put' && method !== 'patch') {
if (data) {
config.params = data;
}
return (axios as any)[method](url, config);
} else if (data && data instanceof FormData) {
config.headers = config.headers || {};
config.headers['Content-Type'] = 'multipart/form-data';
} else if (
data &&
typeof data !== 'string' &&
!(data instanceof Blob) &&
!(data instanceof ArrayBuffer)
) {
data = JSON.stringify(data);
config.headers = config.headers || {};
config.headers['Content-Type'] = 'application/json';
}
return (axios as any)[method](url, data, config);
},
isCancel: (value: any) => (axios as any).isCancel(value),
copy: content => {
copy(content);
toast.success('内容已复制到粘贴板');
}
// 后面这些接口可以不用实现
// 默认是地址跳转
// jumpTo: (
// location: string /*目标地址*/,
// action: any /* action对象*/
// ) => {
// // 用来实现页面跳转, actionType:link、url 都会进来。
// },
// updateLocation: (
// location: string /*目标地址*/,
// replace: boolean /*是replace,还是push?*/
// ) => {
// // 地址替换,跟 jumpTo 类似
// },
// isCurrentUrl: (
// url: string /*url地址*/,
// ) => {
// // 用来判断是否目标地址当前地址
// },
// notify: (
// type: 'error' | 'success' /**/,
// msg: string /*提示内容*/
// ) => {
// toast[type]
// ? toast[type](msg, type === 'error' ? '系统错误' : '系统消息')
// : console.warn('[Notify]', type, msg);
// },
// alert,
// confirm,
}
)}
</div>
);
}
}
render 函数介绍
(schema, props, env) => JSX.Element;
schema
即页面配置,请前往 配置与组件 了解
props
一般都用不上,如果你想传递一些数据给渲染器内部使用,可以传递 data 数据进去。如:
() =>
renderAmis(schema, {
data: {
username: 'amis'
}
});
这样,内部所有组件都能拿到 username
这个变量的值。当然,这里的 key 并不一定必须是 data , 你也可以是其它 key,但必须配合 schema 中的 detectField
属性一起使用。 如:
() =>
renderAmis(
{
//其它配置
detectField: 'somekey'
},
{
somekey: {
username: 'amis'
}
}
);
env
环境变量,可以理解为这个渲染器工具的配置项,需要使用 amis 用户实现部分接口。他有下面若干参数:
fetcher(必须实现)
接口请求器,实现该函数才可以实现 ajax 发送,函数签名如下:
(config: {
url; // 接口地址
method; // 请求方法 get、post、put、delete
data; // 请求数据
responseType;
config; // 其他配置
headers; // 请求头
}) => Promise<fetcherResult>;
你可以使用任何你喜欢的 ajax 请求库来实现这个接口
notify
(type: string, msg: string) => void
用来实现消息提示。
alert
(msg: string) => void
用来实现警告提示。
confirm
(msg: string) => boolean | Promise<boolean>
用来实现确认框。返回 boolean 值
jumpTo
(to: string, action?: Action, ctx?: object) => void
用来实现页面跳转,因为不清楚所在环境中是否使用了 spa 模式,所以用户自己实现吧。
updateLocation
(location: any, replace?: boolean) => void
地址替换,跟 jumpTo 类似。
blockRouting
设置阻止路由跳转的钩子函数,用来实现 form 未保存提前离开时出现确认框。
(fn: (nextLocation:any) => void | string) => () => void;
theme: string
目前支持是三种主题:default
、cxd
和 dark
isCurrentUrl
(link: string) => boolean;
判断目标地址是否为当前页面。
copy
(contents: string, options?: {shutup: boolean})
用来实现内容复制。
session
默认为 'global',决定 store 是否为全局共用的,如果想单占一个 store,请设置不同的值。
getModalContainer
() => HTMLElement;
用来决定弹框容器。
loadRenderer
(schema: any, path: string) => Promise<Function>
可以通过它懒加载自定义组件,比如: https://github.com/baidu/amis/blob/master/tests/factory.test.tsx#L64-L91。
affixOffsetTop: number
固顶间距,当你的有其他固顶元素时,需要设置一定的偏移量,否则会重叠。
affixOffsetBottom: number
固底间距,当你的有其他固底元素时,需要设置一定的偏移量,否则会重叠。
richTextToken: string
内置 rich-text 为 frolaEditor,想要使用,请自行购买,或者用免费的 Tinymce,不设置 token 默认就是 Tinymce。