企业官网建设流程全解析

20 分钟把 amis 接入 React 项目：用 JSON 配置生成后台页面

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis

产品让你加一个"用户列表 + 筛选 + 编辑弹窗"的后台页面，你本来要手写 JSX 再串联状态。而开源低代码框架 amis 能用一份 JSON 配置直接生成整页，并且可以嵌进现有 React 项目，不改技术栈。

先判断值不值得用：3 类场景别硬上

❌ 不建议：

• 交互高度定制的页面（拖拽、画布、复杂动画）：内置渲染器只覆盖后台常见场景，硬套反而费事
• 要求极致首屏性能或精确控制包体积的场景：低代码渲染多一层开销
• 团队完全不会 React：schema 是 JSON，但自定义组件、编辑器插件终究要 React 功底

✅ 适合：

• 后台管理系统、CRUD 列表 + 表单密集型页面
• 需要快速原型验证的项目
• 混合技术栈：npm 方式嵌进 React 项目，或不依赖 npm，像 Vue/jQuery 那样外链 sdk.js 挂到任意页面

快速上手：从 npm 安装到第一个页面 4 步

1. 装核心库：npm i amis。注意官方要求 React>=16.8.6、mobx^4.5.0，版本不一致后面会报错。
2. 装可选依赖：npm i axios copy-to-clipboard，用于示例里的请求和剪贴板，换成你项目里已有的请求库即可。
3. 引入主题样式：cxd 主题需要三个 css，amis/lib/themes/cxd.css、amis/lib/helper.css、amis/sdk/iconfont.css；想要仿 Antd 风格就把第一个换成antd.css。
4. 挂载渲染函数。render(schema, props, env)是三个参数的函数，env 里唯一必须实现的是fetcher。完整步骤可对照 快速开始文档。

import { render as renderAmis } from 'amis'; // 渲染入口 import { ToastComponent, AlertComponent } from 'amis-ui'; // 通知与弹窗容器 // 引入 cxd 主题的三个样式文件 import 'amis/lib/themes/cxd.css'; import 'amis/lib/helper.css'; import 'amis/sdk/iconfont.css'; <ToastComponent theme="cxd" position="top-right" /> <AlertComponent theme="cxd" /> {renderAmis( { type: 'page', title: '我的第一个页面', body: 'Hello amis' }, // schema：页面蓝图 {}, // props：初始数据，比如 { data: { username: 'xx' } } { theme: 'cxd', // 主题名，要和引入的 css 一致 // 唯一必选项：请求适配器，可换成 axios 或你的公司请求层 fetcher: ({ url, method, data, headers }) => axios({ url, method, data, headers }) } )}

概念对齐：写配置前先弄清 4 个术语

核心原理：JSON 是怎么变成 React 组件的

整个渲染过程就一件事：按 type 查注册表，再把属性当 props 传下去。每个节点先拿type去组件池找渲染器，命中就把节点转成对应 React 组件，其余属性全部变成 props；没命中就报"找不到渲染器"。page、form 这类容器组件自己不知道body里装的是什么，所以框架给它们下发一个render回调，调用render('body', body)递归进入下一轮查找。源码级的讲解可以看 amis 工作原理。

另一半是你必须自己写的部分：amis 只负责渲染，网络、跳转、提示都靠 env 注入。fetcher 决定"请求怎么发"；接口有统一包装结构时，不要改 schema 里每个 api，用全局responseAdaptor解包即可；开发用 localhost、线上用正式域名，用replaceText做前缀替换，不用维护两份配置。

当内置类型不够时，注册一个自己的渲染器即可，之后 schema 里用你的 type 就能被识别：

import { Renderer } from 'amis'; // 组件注册工具 // 不支持 Decorator 时改成函数式：Renderer({ type: 'my-status' })(MyStatus) @Renderer({ type: 'my-status', autoVar: true }) // autoVar 自动解析配置里的变量 class MyStatus extends React.Component { render() { // 配置节点里的所有属性都会变成 props const { status } = this.props; return <span>{status === 1 ? '可用' : '离线'}</span>; } } // 注册后即可在 schema 中使用：{ "type": "my-status", "status": 1 }

只想在一处用的话，更轻量的做法是配置里直接写asFormItem: true加children函数，连注册都省了，细节见 自定义组件 - React。

和现有技术栈的结合：请求、路由、状态三个决策点

请求层：fetcher 里调你公司的请求库，token 注入、错误码转提示统一在这一处做；只解包响应结构用responseAdaptor，schema 保持干净。

路由：两种方式二选一。a) 把 amis 当作"某个路由的内容区"，页面切换仍由你的 router 负责，jumpTo、updateLocation用 history 实现；b) 让 amis 管理整站，用内置 app 渲染器配 hash 路由，自己实现isCurrentUrl判断当前地址。单页后台选 a，轻量整站选 b。

状态：初始值走props.data（3.1.0 起还支持context传平台级数据）；外部变化用 scoped 写回全局数据域；amis 内部状态不必接进 Redux，"传进去、写回来、用 scoped 控制"三招就够。另外，官方可视化编辑器amis-editor可以直接嵌进现有后台，让产品或运营自己改页面配置：

// 通过 props 的 scopeRef 回调拿到 scoped（等价于 SDK 里的 amisScoped） amisScoped.updateProps({ data: { currentUser: 'Alice' } }); // 把新数据写回全局数据域 amisScoped.getComponentByName('userTable').reload(); // 按名字重载表格（schema 里要有 name: 'userTable'）

踩坑实录：amis 集成高频问题

1. React 项目集成后报错或渲染异常—— 现象：import 后白屏或报 MobX 相关错误。原因：项目里 Mobx 是 5/6，amis 出于兼容考虑用的是 Mobx 4，5/6 肯定会报错。解决：把 mobx 降到^4.5.0，版本对齐 amis 项目的 package.json。
2. CRUD 分页失效—— 现象：翻页时接口 URL 里没有 page、perPage 参数，返回全量数据。原因：api 地址里带变量（如${id}）时，amis 不会自动附加分页参数。解决：在 URL 里手动拼?page=${page}&perPage=${perPage}。
3. 页面顶部被固定头遮挡—— 现象：项目有吸顶导航，CRUD 顶部工具条被盖住。原因：affixHeader 固顶功能的偏移量默认是 0。解决：3.5.0 起给外层设置--affix-offset-topCSS 变量，或在 schema 里配"affixHeader": false。
4. 返回文本里的 \n 不换行—— 现象：接口返回的换行在页面上挤成一行。原因：浏览器默认折叠连续空白字符。解决：给组件加"wrapperComponent": "pre"或"classname": "white-space-pre"。
5. 开发环境页面异常—— 现象：dev 下渲染错乱，生产正常。原因：React.StrictMode 目前还不支持。解决：把 StrictMode 从 amis 渲染处摘掉。

效果对比：接入 amis 后哪些地方变了

边界说明：后台 CRUD、表单密集类页面是 amis 的甜点位；交互高度定制、追求极致性能或非 Web 形态的页面，仍然建议手写 React。

收尾：读完就能动手的行动清单

• 用 render + fetcher 三步跑通第一个 page 页面
• 把 fetcher 接到公司请求库，统一 token 注入与错误提示
• 实现 jumpTo 和 updateLocation，接入现有路由
• 挑一个真实 CRUD 需求：列表 + 筛选 + 编辑弹窗，用 schema 写完
• 装 amis-editor，把可视化编辑器嵌成后台的"配置页"
• 给关键组件统一加 name 属性，方便 scoped 按名字取组件

【免费下载链接】amis前端低代码框架，通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis