---
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） 申请对应警告邮箱的使用权，获取报错邮件
- 也可以加到悦码渲染器的报错沟通群，跟进自己应用的报错推送

![sentry.dashboard](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250324/企业微信截图_1742796499189.png)

![报错沟通群](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250324/企业微信截图_17427961669787.png)

![sentry 邮箱](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250320/企业微信截图_20250320192100.png)