py-test-component 1.0.11 → 2.0.2

package/DEVELOPER.md

@@ -0,0 +1,541 @@
+# PyComponent 组件库开发指南
+
+本文档面向 AI 模型和开发者，指导如何开发、维护和扩展 `py-test-component` 组件库。
+
+## 目录
+
+1. [架构概述](#架构概述)
+2. [核心原理](#核心原理)
+3. [目录结构](#目录结构)
+4. [添加新组件步骤](#添加新组件步骤)
+5. [代码规范](#代码规范)
+6. [构建流程](#构建流程)
+7. [常见问题](#常见问题)
+
+---
+
+## 架构概述
+
+### 设计目标
+
+- **跨框架**：Vue 2 组件可被 React 使用
+- **零配置**：React 用户无需安装 Vue 和 ElementUI
+- **单一入口**：所有组件统一使用 `propData` 接收参数
+- **状态隔离**：组件库内部 store 不暴露给外部
+
+### 技术栈
+
+| 技术 | 用途 |
+|------|------|
+| Vue 2.7 | 组件开发框架 |
+| ElementUI 2.15 | UI 组件库 |
+| vue-custom-element | Vue 组件转 Web Components |
+| Webpack 5 | 构建工具 |
+
+---
+
+## 核心原理
+
+### 1. Web Components 转换
+
+```
+Vue 组件 --[vue-custom-element]--> 自定义元素 --[React 包装器]--> React 组件
+```
+
+**关键点**：
+- `src/index.js` 使用 `Vue.customElement()` 将 Vue 组件注册为 Web Components
+- Shadow DOM 必须禁用（`shadow: false`），否则 ElementUI 样式无法穿透
+
+### 2. React 适配机制
+
+```javascript
+// src/react/index.js
+function wrapVueComponent(tagName, dataProp) {
+  return forwardRef(function WrappedComponent({ propData, loading, ...props }, ref) {
+    // 1. 动态加载组件库构建产物
+    // 2. 自动注入 ElementUI CSS
+    // 3. 将 propData 设置到自定义元素的 property
+    return <tagName ref={ref} {...props} />;
+  });
+}
+```
+
+**关键点**：
+- React 通过动态 `import()` 加载 `dist/py-component.esm.js`
+- 数据通过直接设置 DOM property（而非 attribute）传递，避免 JSON 序列化
+
+### 3. Store 隔离设计
+
+```
+外部工程 --[initStore]--> 组件库内部 store
+         
+外部无法：
+- 读取 store 状态
+- 订阅 store 变化
+- 获取 store 实例
+```
+
+**实现方式**：
+- `initStore()` 只接受配置对象，不返回任何可操作对象
+- React 版本中 `initStore` 返回 `Promise<void>`，而非 store 实例
+- `window.PyComponent` 仅暴露 `initStore` 方法
+
+---
+
+## 目录结构
+
+```
+py-component/
+├── dist/                          # 构建产物（自动生成）
+│   ├── py-component.js            # UMD 格式
+│   └── py-component.esm.js        # ESM 格式
+│
+├── src/
+│   ├── components/                # Vue 组件源码
+│   │   ├── PyTable.vue
+│   │   └── PyWeather.vue
+│   │
+│   ├── react/                     # React 适配器
+│   │   └── index.js               # 组件包装器 + initStore
+│   │
+│   ├── vue/                       # Vue 入口
+│   │   └── index.js               # 直接导出 Vue 组件
+│   │
+│   ├── store/                     # 全局状态（内部使用）
+│   │   └── index.js               # Vue.observable + get/set/subscribe
+│   │
+│   ├── utils/                     # 工具函数
+│   │   ├── request.js             # fetch 封装
+│   │   └── api.js                 # API 请求封装
+│   │
+│   └── index.js                   # 主入口
+│       # - 注册 Web Components
+│       # - 导出 initStore
+│       # - 挂载到 window.PyComponent
+│
+├── package.json
+├── webpack.config.js              # 双格式构建配置
+├── README.md                      # 用户文档
+├── USAGE.md                       # 使用教程
+└── DEVELOPER.md                   # 本文件
+```
+
+---
+
+## 添加新组件步骤
+
+### 步骤 1：创建 Vue 组件
+
+**文件**：`src/components/PyNewComponent.vue`
+
+```vue
+<template>
+  <div class="py-new-component">
+    <!-- 使用 ElementUI 组件 -->
+    <el-input v-model="innerValue" />
+  </div>
+</template>
+
+<script>
+// 从 store 获取配置（内部使用）
+import store from '../store';
+
+export default {
+  name: 'PyNewComponent',
+  
+  // 统一使用 propData 接收外部数据
+  props: {
+    propData: {
+      default: null  // 不限制类型
+    }
+  },
+  
+  data() {
+    return {
+      innerValue: ''
+    };
+  },
+  
+  computed: {
+    // 根据 propData 类型做适配
+    config() {
+      return this.propData || {};
+    }
+  },
+  
+  mounted() {
+    // 读取 store 中的配置（内部使用）
+    const apiKey = store.get('apiKey');
+    console.log('apiKey:', apiKey);
+  },
+  
+  methods: {
+    handleClick() {
+      // 触发事件供外部监听
+      this.$emit('change', this.innerValue);
+    }
+  }
+};
+</script>
+
+<style scoped>
+.py-new-component {
+  padding: 20px;
+}
+</style>
+```
+
+**要点**：
+- 组件名必须以 `Py` 开头
+- 必须定义 `propData` prop，且不限制类型
+- 使用 `scoped` 样式避免污染
+
+### 步骤 2：注册 Web Component
+
+**文件**：`src/index.js`
+
+```javascript
+import PyNewComponent from './components/PyNewComponent.vue';
+
+// 注册为自定义元素
+Vue.customElement('py-new-component', PyNewComponent, {
+  shadow: false  // 必须禁用 Shadow DOM
+});
+
+// 如有需要，在 window.PyComponent 中保持引用（可选）
+if (typeof window !== 'undefined') {
+  window.PyComponent = { 
+    initStore,
+    // 不暴露 store 实例
+  };
+}
+```
+
+### 步骤 3：Vue 入口导出
+
+**文件**：`src/vue/index.js`
+
+```javascript
+import PyNewComponent from '../components/PyNewComponent.vue';
+
+export { PyTable, PyWeather, PyNewComponent, initStore };
+export default { PyTable, PyWeather, PyNewComponent, initStore };
+```
+
+### 步骤 4：React 入口导出
+
+**文件**：`src/react/index.js`
+
+```javascript
+// 在已有组件后添加
+export const PyNewComponent = wrapVueComponent('py-new-component', 'propData');
+```
+
+**参数说明**：
+- 第一个参数：自定义元素标签名（必须与 `Vue.customElement` 注册时一致）
+- 第二个参数：数据 property 名（统一为 `'propData'`）
+
+### 步骤 5：构建验证
+
+```bash
+npm run build
+```
+
+检查 `dist/` 目录下是否生成新的构建产物。
+
+### 步骤 6：更新文档
+
+- `README.md`：组件列表中添加新组件
+- `USAGE.md`：添加新组件的参数说明和使用示例
+
+---
+
+## 代码规范
+
+### 1. 组件命名
+
+```
+Py + PascalCase
+
+✅ PyTable
+✅ PyWeather
+✅ PyUserForm
+
+❌ py-table      （Vue 组件名用大驼峰）
+❌ PYTABLE       （不要全大写）
+❌ NewComponent  （缺少 Py 前缀）
+```
+
+### 2. Props 规范
+
+```javascript
+// ✅ 正确：统一使用 propData
+props: {
+  propData: {
+    default: null  // 不限制类型，灵活使用
+  }
+}
+
+// ❌ 错误：不要使用多个 props
+props: {
+  data: Array,
+  config: Object,
+  value: String
+}
+```
+
+### 3. Store 使用规范
+
+```javascript
+// ✅ 正确：组件内部读取 store
+import store from '../store';
+
+export default {
+  mounted() {
+    const config = store.get('apiKey');  // 读取
+  },
+  methods: {
+    update() {
+      store.set('key', value);  // 内部组件也可以设置
+    }
+  }
+};
+
+// ❌ 错误：不要在外部暴露 store
+export { store };  // 禁止！
+```
+
+### 4. CSS 规范
+
+```vue
+<style scoped>
+/* ✅ 使用 scoped */
+.py-component-name {
+  /* 组件名作为前缀 */
+}
+
+/* ❌ 不要污染全局 */
+.el-input {
+  /* 这会覆盖 ElementUI 默认样式 */
+}
+</style>
+```
+
+### 5. 事件规范
+
+```javascript
+// ✅ 使用自定义事件与外部通信
+this.$emit('change', value);
+this.$emit('submit', formData);
+
+// ❌ 不要直接操作外部状态
+externalStore.data = value;  // 禁止！
+```
+
+---
+
+## 构建流程
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+- Webpack 监听文件变化
+- 自动重新构建到 `dist/`
+- 不压缩，便于调试
+
+### 生产构建
+
+```bash
+npm run build
+```
+
+- 生成两种格式：
+  - `py-component.js`（UMD，浏览器直接使用）
+  - `py-component.esm.js`（ESM，构建工具使用）
+- 代码压缩，体积优化
+
+### 构建配置要点
+
+**`webpack.config.js`**：
+
+```javascript
+// 关键配置
+const baseConfig = {
+  module: {
+    rules: [
+      { test: /\.vue$/, loader: 'vue-loader' },
+      { test: /\.css$/, use: ['style-loader', 'css-loader'] }
+    ]
+  },
+  resolve: {
+    alias: {
+      'vue$': 'vue/dist/vue.esm.js'  // 使用完整版 Vue
+    }
+  }
+};
+```
+
+---
+
+## 常见问题
+
+### Q1: React 中组件不显示
+
+**排查步骤**：
+1. 检查 `dist/py-component.esm.js` 是否存在
+2. 检查浏览器控制台是否有加载错误
+3. 确认 CSS 是否已注入（`<link>` 标签是否出现在 `<head>`）
+4. 检查 `propData` 是否正确设置到 DOM property
+
+### Q2: ElementUI 样式不生效
+
+**原因**：Shadow DOM 隔离了样式  
+**解决**：确保 `shadow: false`
+
+```javascript
+Vue.customElement('py-component', Component, {
+  shadow: false  // 必须
+});
+```
+
+### Q3: propData 传递后不更新
+
+**原因**：通过 attribute 传递了对象/数组，导致序列化问题  
+**解决**：使用 DOM property 而非 attribute
+
+```javascript
+// ✅ 正确：直接设置 property
+elRef.current.propData = data;
+
+// ❌ 错误：通过 attribute（会导致 JSON 序列化）
+elRef.current.setAttribute('propData', JSON.stringify(data));
+```
+
+### Q4: store 数据在 React 中无法响应
+
+**原因**：Vue.observable 与 React 响应式系统不兼容  
+**设计如此**：store 完全内部化，React 只能设置不能读取  
+**替代方案**：通过组件事件与外部通信
+
+```javascript
+// Vue 组件内
+this.$emit('update', newValue);
+
+// React 中使用
+<PyComponent onUpdate={(e) => console.log(e.detail)} />
+```
+
+### Q5: 如何调试 Web Component
+
+**浏览器控制台**：
+
+```javascript
+// 查看已注册的自定义元素
+customElements.get('py-table');
+
+// 获取组件实例（Vue 内部）
+document.querySelector('py-table').__vue__;
+
+// 手动设置数据
+document.querySelector('py-table').propData = [...];
+```
+
+---
+
+## 扩展建议
+
+### 添加 TypeScript 支持
+
+如需支持 TypeScript：
+
+1. 创建 `index.d.ts`：
+
+```typescript
+declare module 'py-test-component' {
+  export function initStore(config: Record<string, any>): void;
+}
+
+declare module 'py-test-component/vue' {
+  import { Component } from 'vue';
+  export const PyTable: Component;
+  export const PyWeather: Component;
+  export function initStore(config: Record<string, any>): void;
+}
+
+declare module 'py-test-component/react' {
+  import { ForwardRefExoticComponent, RefAttributes } from 'react';
+  
+  interface PyComponentProps {
+    propData?: any;
+    loading?: React.ReactNode;
+  }
+  
+  export const PyTable: ForwardRefExoticComponent<PyComponentProps & RefAttributes<any>>;
+  export const PyWeather: ForwardRefExoticComponent<PyComponentProps & RefAttributes<any>>;
+  export function initStore(config: Record<string, any>): Promise<void>;
+}
+```
+
+2. 在 `package.json` 中添加：
+
+```json
+{
+  "types": "index.d.ts"
+}
+```
+
+### 优化构建体积
+
+当前构建产物包含完整 Vue 和 ElementUI（约 1.1MB）。如需优化：
+
+1. **按需加载 ElementUI 组件**：
+
+```javascript
+// 不使用完整导入
+// import ElementUI from 'element-ui';  // 太大
+
+// 改为按需导入
+import { Table, TableColumn } from 'element-ui';
+Vue.use(Table);
+Vue.use(TableColumn);
+```
+
+2. **配置 Externals**（如果外部工程已引入 Vue）：
+
+```javascript
+// webpack.config.js
+module.exports = {
+  externals: {
+    vue: 'Vue',
+    'element-ui': 'ELEMENT'
+  }
+};
+```
+
+---
+
+## 总结
+
+开发新组件的核心流程：
+
+1. **Vue 组件** → `src/components/PyXxx.vue`
+2. **Web Component 注册** → `src/index.js`
+3. **Vue 入口导出** → `src/vue/index.js`
+4. **React 入口导出** → `src/react/index.js`
+5. **构建验证** → `npm run build`
+6. **更新文档** → `README.md` + `USAGE.md`
+
+**必须遵守的原则**：
+- ✅ 统一使用 `propData` 传递数据
+- ✅ Store 完全内部化，外部只能设置
+- ✅ Web Component 禁用 Shadow DOM
+- ✅ 组件名以 `Py` 开头
+
+---
+
+**维护者备注**：
+
+本文档应与代码同步更新。如修改了核心机制（如 store 设计、数据传递方式），必须同步更新本文档。