# React 示例设置指南

## 快速开始

### 1. 确保 Widget 文件已构建并复制

在项目根目录 (`adp-widget/`) 运行：

```bash
# 构建 widget
npm run build:lib

# 复制到示例项目的 public 目录
npm run copy:examples
```

### 2. 安装依赖

```bash
cd examples/react-example
npm install
```

### 3. 运行开发服务器

```bash
npm run dev
```

浏览器会自动打开 `http://localhost:5173`

## 故障排查

### Widget 不显示（宽高为 0）

**可能原因：**

1. Web Component 文件未正确加载
2. 文件路径不正确
3. CSS 样式未加载

**解决方案：**

1. **检查文件是否存在**

   ```bash
   ls -la public/widget/
   ```

   应该看到：

   - `adp-widget.es.js`
   - `omi-starter-ts.css`

2. **检查浏览器控制台**

   - 打开开发者工具 (F12)
   - 查看 Console 是否有错误
   - 查看 Network 标签，确认文件已加载（应该看到 `/widget/adp-widget.es.js` 和 `/widget/omi-starter-ts.css`）

3. **重新构建和复制**

   ```bash
   cd ../../  # 回到 adp-widget 目录
   npm run build:lib
   npm run copy:examples
   cd examples/react-example
   npm run dev
   ```

4. **检查 adp-widget 元素**
   在浏览器控制台运行：

   ```javascript
   document.querySelector("adp-widget");
   ```

   应该返回元素对象，而不是 null

5. **验证 Web Component 已注册**
   ```javascript
   customElements.get("adp-widget");
   ```
   应该返回组件类，而不是 undefined

### Vite 错误："Cannot use 'in' operator..."

这个错误已经修复。现在使用 `public` 目录来存放 Web Component 文件，避免 Vite 尝试转换已打包的文件。

**解决方案：**

- 确保文件在 `public/widget/` 目录下
- 在 HTML 中使用 `/widget/` 路径引用（不是 `@shared`）

## 文件结构

```
react-example/
├── public/
│   └── widget/           # ← Web Component 文件在这里
│       ├── adp-widget.es.js
│       └── omi-starter-ts.css
├── src/
│   ├── main.tsx          # 入口文件
│   ├── App.tsx           # 主应用
│   └── components/
│       ├── WidgetDemo.tsx    # Widget 演示组件
│       └── JsonEditor.tsx    # JSON 编辑器
└── index.html            # HTML 入口，引入 Web Component
```

## 工作原理

1. **index.html** 在 `<head>` 中引入 Web Component：

   ```html
   <script type="module" src="/widget/adp-widget.es.js"></script>
   <link rel="stylesheet" href="/widget/omi-starter-ts.css" />
   ```

2. **Vite 的 public 目录**：

   - `public/` 目录下的文件会被直接复制到构建输出
   - 使用 `/` 开头的路径可以直接访问 public 目录下的文件
   - 不会被 Vite 转换或打包

3. **WidgetDemo.tsx** 使用 Web Component：
   ```tsx
   <adp-widget ref={widgetRef} widget-json={JSON.stringify(config)} />
   ```

## 常见问题

### Q: 为什么使用 public 目录而不是动态导入？

A: 因为 `adp-widget.es.js` 是已经打包好的文件，包含了所有依赖。如果通过 Vite 动态导入，Vite 会尝试转换它，可能导致错误。使用 public 目录可以让文件直接被浏览器加载，不经过 Vite 处理。

### Q: 每次构建后都要手动复制文件吗？

A: 不需要。运行 `npm run copy:examples` 会自动复制文件到所有示例项目的 public 目录。

### Q: 如何调试 Widget 内部？

A:

1. 打开浏览器开发者工具
2. 找到 `<adp-widget>` 元素
3. 展开 Shadow DOM
4. 查看内部结构和样式

### Q: 为什么要在 HTML 而不是 JS 中引入？

A: 在 HTML 的 `<head>` 中引入可以确保 Web Component 在 React 应用启动前就已经注册，避免时序问题。
