amis2/docs/getting_started.md
upeng e982da5b5a
Update getting_started.md
js 和 css 引用位置写反了
2020-06-11 10:43:28 +08:00

283 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: 快速开始
---
有两种方式使用 amis
1. [React 组件](#React 组件),可以整合到 React 项目中,适合熟悉 React 的开发者,可以[开发自定义组件进行扩展](../custom)。
2. [JSSDK](#JSSDK),可以放到任意页面中使用,能使用 amis 内置的渲染组件,但无法开发自定义组件,适合不使用 React 的项目或不熟悉前端的开发者。
## React 组件
### 安装依赖
直接通过 npm 安装即可。
```
npm i amis
```
### 整合到 React 组件中
可以在 React Component 这么使用TypeScript
```tsx
import * as React from 'react';
import {
render as renderAmis
} from 'amis';
class MyComponent extends React.Component<any, any> {
render() {
return (
<div>
<p>通过 amis 渲染页面</p>
{renderAmis({
// schema
// 这里是 amis 的 Json 配置。
type: 'page',
title: '简单页面',
body: '内容'
}, {
// props
}, {
// env
// 这些是 amis 需要的一些接口实现
// 可以参考本项目里面的 Demo 部分代码。
updateLocation: (location:string/*目标地址*/, replace:boolean/*是replace还是push*/) => {
// 用来更新地址栏
},
jumpTo: (location:string/*目标地址*/) => {
// 页面跳转, actionType: link、url 都会进来。
},
fetcher: ({
url,
method,
data,
config
}:{
url:string/*目标地址*/,
method:'get' | 'post' | 'put' | 'delete'/*发送方式*/,
data: object | void/*数据*/,
config: object/*其他配置*/
}) => {
// 用来发送 Ajax 请求,建议使用 axios
},
notify: (type:'error'|'success'/**/, msg:string/*提示内容*/) => {
// 用来提示用户
},
alert: (content:string/*提示信息*/) => {
// 另外一种提示,可以直接用系统框
},
confirm: (content:string/*提示信息*/) => {
// 确认框。
}
});}
</div>
);
}
}
```
`(schema:Schema, props?:any, env?: any) => JSX.Element`
参数说明:
- `schema` 即页面配置,请前往[基本用法](./basic.md)了解.
- `props` 一般都用不上,如果你想传递一些数据给渲染器内部使用,可以传递 data 数据进去。如:
```jsx
() =>
renderAmis(schema, {
data: {
username: 'amis'
}
});
```
这样,内部所有组件都能拿到 `username` 这个变量的值。
- `env` 环境变量,可以理解为这个渲染器工具的配置项,需要调用者实现部分接口。
- `session: string` 默认为 'global',决定 store 是否为全局共用的,如果想单占一个 store请设置不同的值。
- `fetcher: (config: fetcherConfig) => Promise<fetcherResult>` 用来实现 ajax 发送。
示例
```js
fetcher: ({
url,
method,
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: (e:error) => boolean` 判断 ajax 异常是否为一个 cancel 请求。
示例
```js
isCancel: (value: any) => (axios as any).isCancel(value)
```
- `notify: (type:string, msg: string) => void` 用来实现消息提示。
- `alert: (msg:string) => void` 用来实现警告提示。
- `confirm: (msg:string) => boolean | Promise<boolean>` 用来实现确认框。
- `jumpTo: (to:string, action?: Action, ctx?: object) => void` 用来实现页面跳转,因为不清楚所在环境中是否使用了 spa 模式,所以用户自己实现吧。
- `updateLocation: (location:any, replace?:boolean) => void` 地址替换,跟 jumpTo 类似。
- `isCurrentUrl: (link:string) => boolean` 判断目标地址是否为当前页面。
- `theme: 'default' | 'cxd'` 目前支持两种主题。
- `copy: (contents:string, options?: {shutup: boolean}) => void` 用来实现,内容复制。
- `getModalContainer: () => HTMLElement` 用来决定弹框容器。
- `loadRenderer: (chema: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 渲染器。
## JSSDK
JSSDK 适合对前端或 React 不了解的开发者,它不依赖 npm 及 webpack直接引入代码就能使用但需要注意这种方式不支持[定制组件](../sdk),只能使用 amis 内置的组件。
JSSDK 的代码从以下地址获取:
- JS https://houtai.baidu.com/v2/jssdk
- CSS https://houtai.baidu.com/v2/csssdk
然后在页面中插入下面的代码就能渲染出来了:
```js
(function () {
var amis = amisRequire('amis/embed');
amis.embed(
'#container',
{
type: 'page',
title: 'AMIS Demo',
body: 'This is a simple amis page.'
},
{
// props 一般不用传。
},
{
// env
fetcher: () => {
// 可以不传,用来实现 ajax 请求
},
jumpTo: () => {
// 可以不传,用来实现页面跳转
},
updateLocation: () => {
// 可以不传,用来实现地址栏更新
},
isCurrentUrl: () => {
// 可以不传,用来判断是否目标地址当前地址。
},
copy: () => {
// 可以不传,用来实现复制到剪切板
},
notify: () => {
// 可以不传,用来实现通知
},
alert: () => {
// 可以不传,用来实现提示
},
confirm: () => {
// 可以不传,用来实现确认框。
}
}
);
})();
```
注意:以上的 SDK 地址是一个页面跳转,会跳转到一个 CDN 地址,而且每次跳转都是最新的版本,随着 amis 的升级这个地址会一直变动,如果你的页面已经完成功能回归,请直接使用某个固定地址,这样才不会因为 amis 升级而导致你的页面不可用。
另外sdk 代码也伴随 npm 一起发布了,不使用 CDN 版本,直接替换成 npm 包里面的 `amis/sdk.js``amis/sdk.css` 即可。
完整示例:
```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="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 () {
var amis = amisRequire('amis/embed');
amis.embed('#root', {
type: 'page',
title: 'AMIS Demo',
body: 'hello world'
});
})();
</script>
</body>
</html>
```