amis/docs/start/getting-started.md

466 lines
11 KiB
Markdown
Raw Normal View History

2020-07-28 14:55:49 +08:00
---
title: 快速开始
description:
---
2020-08-12 16:39:54 +08:00
amis 有两种使用方法:
- [npm](#npm)
- [JS SDK](#SDK)
npm 适合用在 React 项目中,可以完整使用 amis 的所有功能,方便扩展。
SDK 适合对前端或 React 不了解的开发者,它不依赖 npm 及 webpack直接引入代码就能使用但需要注意这种方式难以支持 [自定义组件](./custom),只能使用 amis 内置的组件。
2020-07-28 14:55:49 +08:00
## npm
### 安装
```
npm i amis
```
2020-08-04 10:55:22 +08:00
### 主题样式
目前支持三种主题:`default默认主题`、`cxd云舍`和`dark暗黑`
1. 引入样式文件:
2020-08-04 13:16:20 +08:00
html 中引入:
2020-08-04 10:55:22 +08:00
```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 中引入:
```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';
```
> 上面只是示例,请根据自己的项目结构调整引用路径
2. 渲染器使用配置主题
```js
renderAmis(
{
type: 'page',
title: '简单页面',
body: '内容'
},
2020-08-04 13:16:20 +08:00
{},
2020-08-04 10:55:22 +08:00
{
// env...
2020-08-04 13:16:20 +08:00
theme: 'default' // cxd 或 dark
2020-08-04 10:55:22 +08:00
}
);
```
2020-08-18 18:53:18 +08:00
### 使用指南
2020-07-28 14:55:49 +08:00
可以在 React Component 这么使用TypeScript
2020-08-18 18:53:18 +08:00
1. 安装部分示例需要的插件库
```
npm i axios copy-to-clipboard
```
> 为了方便示例,上面选用了我们常用几个插件库,你完全可以选择自己喜欢的插件并重新实现
2020-09-11 12:58:20 +08:00
2. 代码实现React Typescript
2020-08-18 18:53:18 +08:00
2020-07-28 14:55:49 +08:00
```tsx
import * as React from 'react';
2020-08-18 18:53:18 +08:00
import axios from 'axios';
import copy from 'copy-to-clipboard';
2020-08-04 10:55:22 +08:00
import {render as renderAmis} from 'amis';
2020-08-18 18:53:18 +08:00
import {alert, confirm} from 'amis/lib/components/Alert';
import {toast} from 'amis/lib/components/Toast';
2020-07-28 14:55:49 +08:00
class MyComponent extends React.Component<any, any> {
2020-08-04 10:55:22 +08:00
render() {
return (
<div>
<p>通过 amis 渲染页面</p>
{renderAmis(
{
// 这里是 amis 的 Json 配置。
type: 'page',
title: '简单页面',
body: '内容'
},
{
2020-08-18 18:53:18 +08:00
// props...
2020-08-04 10:55:22 +08:00
},
{
// env
// 这些是 amis 需要的一些接口实现
// 可以参考后面的参数介绍。
2020-08-20 15:50:36 +08:00
jumpTo: (
location: string /*目标地址*/,
action: any /* action对象*/
) => {
2020-08-18 18:53:18 +08:00
// 用来实现页面跳转, actionType:link、url 都会进来。
// 因为不清楚所在环境中是否使用了 spa 模式,所以自己实现这个方法吧。
},
2020-08-04 10:55:22 +08:00
updateLocation: (
location: string /*目标地址*/,
replace: boolean /*是replace还是push*/
) => {
2020-08-18 18:53:18 +08:00
// 地址替换,跟 jumpTo 类似
2020-08-04 10:55:22 +08:00
},
fetcher: ({
2020-08-18 18:53:18 +08:00
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);
2020-08-04 10:55:22 +08:00
},
2020-08-18 18:53:18 +08:00
isCancel: (value: any) => (axios as any).isCancel(value),
2020-08-04 10:55:22 +08:00
notify: (
type: 'error' | 'success' /**/,
msg: string /*提示内容*/
) => {
2020-08-18 18:53:18 +08:00
toast[type]
? toast[type](msg, type === 'error' ? '系统错误' : '系统消息')
: console.warn('[Notify]', type, msg);
2020-08-04 10:55:22 +08:00
},
2020-08-18 18:53:18 +08:00
alert,
confirm,
copy: content => {
copy(content);
toast.success('内容已复制到粘贴板');
2020-08-04 10:55:22 +08:00
}
}
)}
</div>
);
}
2020-07-28 14:55:49 +08:00
}
```
2020-08-18 18:53:18 +08:00
### render 函数介绍
```js
(schema, props, env) => JSX.Element;
```
#### schema
即页面配置,请前往 [配置与组件](../concepts/schema) 了解
#### props
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
一般都用不上,如果你想传递一些数据给渲染器内部使用,可以传递 data 数据进去。如:
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
```jsx
() =>
renderAmis(schema, {
data: {
username: 'amis'
}
});
```
这样,内部所有组件都能拿到 `username` 这个变量的值。当然,这里的 key 并不一定必须是 data , 你也可以是其它 key但必须配合 schema 中的 `detectField` 属性一起使用。 如:
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
```jsx
() =>
renderAmis(
{
//其它配置
detectField: 'somekey'
},
{
somekey: {
2020-07-28 14:55:49 +08:00
username: 'amis'
}
2020-08-18 18:53:18 +08:00
}
);
```
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
#### env
2020-08-12 16:39:54 +08:00
2020-08-18 18:53:18 +08:00
环境变量,可以理解为这个渲染器工具的配置项,需要使用 amis 用户实现部分接口。他有下面若干参数:
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
##### fetcher必须实现
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
接口请求器,实现该函数才可以实现 ajax 发送,函数签名如下:
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
```ts
(config: {
url; // 接口地址
method; // 请求方法 get、post、put、delete
data; // 请求数据
responseType;
config; // 其他配置
headers; // 请求头
}) => Promise<fetcherResult>;
```
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
> 你可以使用任何你喜欢的 ajax 请求库来实现这个接口
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
##### notify
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
```ts
(type: string, msg: string) => void
```
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
用来实现消息提示。
2020-07-28 14:55:49 +08:00
2020-08-18 18:53:18 +08:00
##### alert
```ts
(msg: string) => void
```
用来实现警告提示。
##### confirm
```ts
(msg: string) => boolean | Promise<boolean>
```
用来实现确认框。返回 boolean 值
##### jumpTo
```ts
(to: string, action?: Action, ctx?: object) => void
```
用来实现页面跳转,因为不清楚所在环境中是否使用了 spa 模式,所以用户自己实现吧。
##### updateLocation
```ts
(location: any, replace?: boolean) => void
```
地址替换,跟 jumpTo 类似。
##### theme: string
目前支持是三种主题:`default`、`cxd` 和 `dark`
##### isCurrentUrl
```ts
(link: string) => boolean;
```
判断目标地址是否为当前页面。
##### copy
```ts
(contents: string, options?: {shutup: boolean})
```
用来实现内容复制。
##### session
默认为 'global',决定 store 是否为全局共用的,如果想单占一个 store请设置不同的值。
##### getModalContainer
```ts
() => HTMLElement;
```
用来决定弹框容器。
##### loadRenderer
```ts
(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想要使用请自行购买或者自己实现 rich-text 渲染器。
2020-07-28 14:55:49 +08:00
## SDK
JSSDK 的代码从以下地址获取:
- JS https://houtai.baidu.com/v2/jssdk
- CSS https://houtai.baidu.com/v2/csssdk
2020-08-19 12:01:28 +08:00
以上的 SDK 地址是一个页面跳转,会跳转到一个 CDN 地址,而且每次跳转都是最新的版本,随着 amis 的升级这个地址会一直变动。npm 包里面也包含 sdk 文件,要固定某个版本可以先 amis 安装到本地,然后去 sdk 目录拷贝文件。然后类似如下的方式使用:
2020-07-28 14:55:49 +08:00
```html
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8" />
2020-08-21 15:28:22 +08:00
<title>amis demo</title>
2020-07-28 14:55:49 +08:00
<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="amis/sdk.css" />
<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="amis/sdk.js"></script>
<script type="text/javascript">
(function () {
2020-08-13 21:32:49 +08:00
let amis = amisRequire('amis/embed');
let amisScoped = amis.embed('#root', {
2020-07-28 14:55:49 +08:00
type: 'page',
2020-08-21 15:28:22 +08:00
title: 'amis demo',
2020-07-28 14:55:49 +08:00
body: 'hello world'
});
})();
</script>
</body>
</html>
```
2020-08-12 16:39:54 +08:00
2020-08-13 21:32:49 +08:00
### 控制 amis 的行为
2020-08-12 16:39:54 +08:00
`amis.embed` 函数还支持以下配置项来控制 amis 的行为,比如在 fetcher 的时候加入自己的处理逻辑,这些函数参数的说明在前面也有介绍。
```js
2020-08-13 21:32:49 +08:00
let amisScoped = amis.embed(
2020-08-12 16:39:54 +08:00
'#root',
{
type: 'page',
2020-08-21 15:28:22 +08:00
title: 'amis demo',
2020-08-12 16:39:54 +08:00
body: 'This is a simple amis page.'
},
{
// props 一般不用传。
},
{
fetcher: (url, method, data, config) => {
// 可以不传,用来实现 ajax 请求
},
2020-08-18 18:53:18 +08:00
jumpTo: location => {
2020-08-12 16:39:54 +08:00
// 可以不传,用来实现页面跳转
},
updateLocation: (location, replace) => {
// 可以不传,用来实现地址栏更新
},
2020-08-18 18:53:18 +08:00
isCurrentUrl: url => {
2020-08-12 16:39:54 +08:00
// 可以不传,用来判断是否目标地址当前地址。
},
2020-08-18 18:53:18 +08:00
copy: content => {
2020-08-12 16:39:54 +08:00
// 可以不传,用来实现复制到剪切板
},
notify: (type, msg) => {
// 可以不传,用来实现通知
},
2020-08-18 18:53:18 +08:00
alert: content => {
2020-08-12 16:39:54 +08:00
// 可以不传,用来实现提示
},
2020-08-18 18:53:18 +08:00
confirm: content => {
2020-08-12 16:39:54 +08:00
// 可以不传,用来实现确认框。
}
}
);
2020-08-13 21:32:49 +08:00
```
同时返回的 `amisScoped` 对象可以获取到 amis 渲染的内部信息,它有如下方法:
`getComponentByName(name)` 用于获取渲染出来的组件,比如下面的示例
```json
{
"type": "page",
"name": "page1",
"title": "表单页面",
"body": {
2020-08-18 18:53:18 +08:00
"type": "form",
"name": "form1",
"controls": [
{
"label": "Name",
"type": "text",
"name": "name1"
}
]
2020-08-13 21:32:49 +08:00
}
}
```
可以通过 `amisScoped.getComponentByName('page1.form1').getValues()` 来获取到所有表单的值,需要注意 page 和 form 都需要有 name 属性。