188 lines
5.4 KiB
Markdown
188 lines
5.4 KiB
Markdown
---
|
||
outline: deep
|
||
---
|
||
|
||
# 快速开始 {#quick-start}
|
||
|
||
## 前置准备
|
||
|
||
::: info 适用项目
|
||
|
||
- vue2
|
||
- vue3
|
||
- react
|
||
- 其他框架请联系伊利（sy）或王雪峰（sy3570）添加适配器
|
||
|
||
## 环境要求
|
||
|
||
- node >= 20
|
||
- vue2 > 2.7.0
|
||
- vue3 > 3.5.0
|
||
- react > 18.0.0
|
||
|
||
## 准备工作
|
||
|
||
1. npmrc 配置文件增加镜像指定，sy 组件库走 shiyue 源，其他走淘宝镜像
|
||
|
||
```bash
|
||
# .npmrc
|
||
registry=https://registry.npmmirror.com
|
||
@sy:registry=http://sy-registry.shiyue.com
|
||
```
|
||
|
||
2. node 至少要升级为 20 以上的版本
|
||
|
||
```bash
|
||
nvm install 20
|
||
nvm use 20
|
||
```
|
||
|
||
若不可行，请查看 node 官网历代大版本的 lts 版本（长期维护），自行安装，查看是否能正常渲染，选取稳定渲染悦码的那一个 node 版本作为开发环境
|
||
|
||
:::
|
||
|
||
## 接入方式
|
||
|
||
### vue2 项目接入
|
||
|
||
```bash
|
||
pnpm i @sy/wujie-vue2-renderer-adapter@latest --save
|
||
# or 或者
|
||
npm i @sy/wujie-vue2-renderer-adapter@latest --save
|
||
```
|
||
|
||
```vue
|
||
<script>
|
||
import WujieVueRendererAdapter from '@sy/wujie-vue2-renderer-adapter';
|
||
</script>
|
||
|
||
<template>
|
||
<!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
|
||
<WujieVueRendererAdapter fileId="test123" projectId="test123" />
|
||
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
|
||
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
|
||
<WujieVueRendererAdapter
|
||
fileId="test123"
|
||
projectId="test123"
|
||
degrade="true"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
### vue3 项目接入
|
||
|
||
```bash
|
||
pnpm i @sy/wujie-vue3-renderer-adapter@latest --save
|
||
# or 或者
|
||
npm i @sy/wujie-vue3-renderer-adapter@latest --save
|
||
```
|
||
|
||
#### 路由形式使用
|
||
|
||
```ts
|
||
import type { RouteRecordRaw } from 'vue-router';
|
||
|
||
import RendererAdapter from '@sy/vue3-renderer-adapter';
|
||
|
||
import { isDevMode, LOW_CODE_PROJECT_ID, VITE_DESIGNER_URL } from '@/constants';
|
||
import router from '@/router';
|
||
|
||
const routes: RouteRecordRaw[] = [
|
||
{
|
||
path: '/micro',
|
||
name: 'Micro',
|
||
meta: {
|
||
title: '微应用容器',
|
||
icon: 'ant-design:appstore-outlined',
|
||
},
|
||
children: [
|
||
{
|
||
path: 'admin-designer',
|
||
name: 'AdminDesigner',
|
||
meta: {
|
||
hideInMenu: !isDevMode,
|
||
title: '平台设计器',
|
||
icon: 'ant-design:edit-outlined',
|
||
},
|
||
component: RendererAdapter,
|
||
// 可动态注入 props,根据必要性，可以注入 route 等参数
|
||
// 悦码里通过 ctxProps 获取，意思为上下文参数
|
||
props: (route) => {
|
||
return {
|
||
url: `${VITE_DESIGNER_URL}`,
|
||
projectId: LOW_CODE_PROJECT_ID,
|
||
fileId: 'test123',
|
||
// 你还可以提供 父应用的 router，来实现子应用执行父应用的 router 方法来实现跳转
|
||
router, // 悦码里通过 ctxProps.router 调用
|
||
query: {
|
||
...route.query,
|
||
},
|
||
};
|
||
},
|
||
},
|
||
],
|
||
},
|
||
];
|
||
|
||
export default routes;
|
||
```
|
||
|
||
#### 组件形式使用
|
||
|
||
```vue
|
||
<script setup>
|
||
import WujieVueRendererAdapter from '@sy/wujie-vue3-renderer-adapter';
|
||
</script>
|
||
|
||
<template>
|
||
<!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
|
||
<WujieVueRendererAdapter fileId="test123" projectId="test123" />
|
||
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
|
||
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
|
||
<WujieVueRendererAdapter
|
||
fileId="test123"
|
||
projectId="test123"
|
||
degrade="true"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
### react 项目接入
|
||
|
||
```bash
|
||
pnpm i @sy/wujie-react-renderer-adapter@latest --save
|
||
# or 或者
|
||
npm i @sy/wujie-react-renderer-adapter@latest --save
|
||
```
|
||
|
||
```jsx
|
||
import WujieReactRendererAdapter from '@sy/wujie-react-renderer-adapter';
|
||
|
||
return <WujieReactRendererAdapter fileId="test123" projectId="test123" />;
|
||
```
|
||
|
||
## API 参考
|
||
|
||
- 6.1 Props 参数详解
|
||
- 6.2 事件监听与回调
|
||
- 6.3 实例方法
|
||
- 6.4 拦截器使用
|
||
|
||
## 故障排除
|
||
|
||
- 常见错误及解决方案
|
||
- 日志与调试
|
||
- 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记
|
||
- 兼容性问题处理
|
||
- renderer-adapter 是默认使用无界微应用来加载悦码渲染器应用的，这种集成方式会让悦码与你的父应用有更深的上下文结合和交互，但有一定的兼容性问题，当出现你无法解决的兼容性问题时，你可以手动设置 `degrade` 为 `false`，这将开启传统降级渲染，使用无界 iframe 加载悦码渲染器应用，若还不行，可摇人处理（王雪峰：sy3570）
|
||
|
||
- 性能问题诊断
|
||
- 悦码渲染器内部使用了 sentry 上报错误，你可以跟 徐川（sy0182） 申请对应警告邮箱的使用权，获取报错邮件
|
||
- 也可以加到悦码渲染器的报错沟通群，跟进自己应用的报错推送
|
||
|
||
|
||
|
||
|
||
|
||
|