py-test-component 1.0.11 → 2.0.2

package/README.md

@@ -0,0 +1,201 @@
+# py-test-component
+
+Vue2 + ElementUI 组件库，支持在 React 项目中使用。
+
+## 功能特性
+
+- **跨框架支持**：Vue 2 项目原生使用，React 项目无缝集成
+- **Web Components 技术**：基于 `vue-custom-element` 将 Vue 组件转换为自定义元素
+- **统一 API**：Vue 和 React 项目使用相同的组件接口
+- **自动样式注入**：React 使用时自动加载 ElementUI CSS
+- **全局状态管理**：内置基于 Vue.observable 的 store，支持跨组件状态共享
+
+## 组件列表
+
+| 组件 | 说明 | 参数 |
+|------|------|------|
+| PyTable | 表格展示组件 | `propData`: 任意类型数据 |
+| PyWeather | 天气查询组件 | `propData`: 配置对象 |
+
+## 项目结构
+
+```
+py-component/
+├── dist/                    # 构建产物
+│   ├── py-component.js      # UMD 格式（浏览器直接使用）
+│   └── py-component.esm.js  # ESM 格式（构建工具使用）
+├── src/
+│   ├── components/          # Vue 组件源码
+│   │   ├── PyTable.vue
+│   │   └── PyWeather.vue
+│   ├── react/               # React 适配器
+│   │   └── index.js         # React 组件包装器
+│   ├── vue/                 # Vue 入口
+│   │   └── index.js         # 直接导出 Vue 组件
+│   ├── store/               # 全局状态管理
+│   │   └── index.js
+│   ├── utils/               # 工具函数
+│   │   ├── api.js           # API 封装
+│   │   └── request.js       # fetch 请求封装
+│   └── index.js             # 主入口（Web Components 注册）
+├── package.json
+└── webpack.config.js
+```
+
+## 开发教程
+
+### 环境准备
+
+```bash
+cd py-component
+npm install
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+监听文件变化，自动重新构建。
+
+### 生产构建
+
+```bash
+npm run build
+```
+
+生成 `dist/py-component.js` 和 `dist/py-component.esm.js`。
+
+### 添加新组件
+
+1. **创建 Vue 组件** `src/components/PyNewComponent.vue`：
+
+```vue
+<template>
+  <div class="py-new-component">
+    <!-- 组件内容 -->
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'PyNewComponent',
+  props: {
+    propData: {
+      default: null
+    }
+  }
+};
+</script>
+```
+
+2. **注册 Web Component**（`src/index.js`）：
+
+```javascript
+import PyNewComponent from './components/PyNewComponent.vue';
+
+Vue.customElement('py-new-component', PyNewComponent, {
+  shadow: false
+});
+```
+
+3. **Vue 入口导出**（`src/vue/index.js`）：
+
+```javascript
+import PyNewComponent from '../components/PyNewComponent.vue';
+export { PyNewComponent };
+```
+
+4. **React 入口导出**（`src/react/index.js`）：
+
+```javascript
+export const PyNewComponent = wrapVueComponent('py-new-component', 'propData');
+```
+
+## 发布教程
+
+### 1. 更新版本号
+
+```bash
+npm version patch   # 补丁版本 1.0.0 -> 1.0.1
+npm version minor   # 次要版本 1.0.0 -> 1.1.0
+npm version major   # 主要版本 1.0.0 -> 2.0.0
+```
+
+### 2. 构建产物
+
+```bash
+npm run build
+```
+
+### 3. 发布到 npm
+
+```bash
+npm publish
+```
+
+### 4. 本地测试（模拟发布）
+
+在测试项目中使用 `file:` 协议引用：
+
+```json
+{
+  "dependencies": {
+    "py-test-component": "file:../py-component"
+  }
+}
+```
+
+## 注意事项
+
+### 1. CSS 加载
+
+- **Vue 项目**：需自行引入 ElementUI CSS
+  ```javascript
+  import 'element-ui/lib/theme-chalk/index.css';
+  ```
+
+- **React 项目**：CSS 自动注入（通过 CDN），无需手动引入
+
+### 2. 组件数据传递
+
+所有组件统一使用 `propData` 属性传递数据，不限制数据类型：
+
+```javascript
+// 可以是数组
+<PyTable :propData="[{ name: '张三' }]" />
+
+// 可以是对象
+<PyWeather :propData="{ city: '北京' }" />
+
+// 可以是任意类型
+<AnyComponent :propData="任意值" />
+```
+
+### 3. Store 使用限制
+
+- **Vue 项目**：可直接使用响应式 store
+- **React 项目**：只能通过 `initStore` 设置值，无法直接获取（因 Vue.observable 与 React 响应式系统不兼容）
+
+### 4. 构建体积
+
+当前构建产物包含 Vue 和 ElementUI 完整代码（约 1.1MB），如需优化体积，建议配置 Webpack externals 将依赖作为 peerDependencies 外部化。
+
+### 5. 浏览器兼容性
+
+- 支持现代浏览器（Chrome、Firefox、Safari、Edge）
+- IE11 需要 polyfill
+
+## 目录说明
+
+| 目录/文件 | 说明 |
+|-----------|------|
+| `dist/` | 构建产物，发布时包含 |
+| `src/components/` | Vue 组件源码 |
+| `src/react/` | React 适配器代码 |
+| `src/vue/` | Vue 直接入口 |
+| `src/store/` | 全局状态管理 |
+| `src/utils/` | 工具函数（请求、API） |
+| `vue-test/` | Vue 测试工程（同级目录） |
+| `react-test/` | React 测试工程（同级目录） |

package/USAGE.md

@@ -0,0 +1,366 @@
+# 使用文档
+
+本文档介绍如何在 Vue 和 React 项目中使用 `py-test-component` 组件库。
+
+---
+
+## Vue 项目使用
+
+### 1. 安装
+
+```bash
+npm install py-test-component
+```
+
+### 2. 引入 ElementUI CSS
+
+在入口文件（如 `main.js`）中引入 ElementUI 样式：
+
+```javascript
+import Vue from 'vue';
+import 'element-ui/lib/theme-chalk/index.css';  // 必须引入
+import { initStore } from 'py-test-component';
+
+// 初始化组件库配置（仅设置，配置仅供组件库内部使用）
+initStore({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com'
+});
+```
+
+**注意**：`initStore` 只能设置配置，无法读取 store 状态，避免与外部工程的状态管理冲突。
+
+### 3. 使用组件
+
+#### 方式一：按需导入组件
+
+```vue
+<template>
+  <div>
+    <PyTable :propData="tableData" />
+    <PyWeather />
+  </div>
+</template>
+
+<script>
+import { PyTable, PyWeather } from 'py-test-component/vue';
+
+export default {
+  components: {
+    PyTable,
+    PyWeather
+  },
+  data() {
+    return {
+      tableData: [
+        { date: '2024-01-01', name: '张三', address: '北京市' },
+        { date: '2024-01-02', name: '李四', address: '上海市' }
+      ]
+    };
+  }
+};
+</script>
+```
+
+#### 方式二：全局注册
+
+```javascript
+// main.js
+import { PyTable, PyWeather } from 'py-test-component/vue';
+
+Vue.component('PyTable', PyTable);
+Vue.component('PyWeather', PyWeather);
+```
+
+### 4. 组件参数
+
+#### PyTable
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| propData | any | null | 表格数据，需为数组格式 |
+
+```vue
+<PyTable :propData="[
+  { date: '2024-01-01', name: '张三', address: '北京' }
+]" />
+```
+
+#### PyWeather
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| propData | object | null | 可选配置，如 `{ city: '北京' }` |
+
+```vue
+<PyWeather :propData="{ city: '北京' }" />
+```
+
+### 5. initStore 配置
+
+```javascript
+import { initStore } from 'py-test-component';
+
+// 同步调用，仅设置配置到组件库内部 store
+// 配置仅供组件库内部使用，外部无法读取
+initStore({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com',
+  // 任意自定义配置
+});
+```
+
+**重要**：`initStore` 只能写入配置，外部工程无法通过任何方式读取 store 状态，确保不会污染外部工程的状态管理。
+
+---
+
+## React 项目使用
+
+### 1. 安装
+
+```bash
+npm install py-test-component
+```
+
+### 2. 初始化配置
+
+在入口文件（如 `index.js`）中初始化：
+
+```javascript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { initStore } from 'py-test-component/react';
+import App from './App';
+
+// 异步初始化（返回 Promise，不返回 store）
+initStore({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com'
+}).then(() => {
+  console.log('组件库初始化完成');
+});
+
+// 或者使用 async/await
+async function bootstrap() {
+  await initStore({ apiKey: 'xxx' });
+  
+  const root = ReactDOM.createRoot(document.getElementById('root'));
+  root.render(<App />);
+}
+bootstrap();
+```
+
+**注意**：`initStore` 返回的 Promise 不会 resolve store 实例，仅表示初始化完成。
+
+### 3. 使用组件
+
+```jsx
+import React, { useState } from 'react';
+import { PyTable, PyWeather } from 'py-test-component/react';
+
+function MyComponent() {
+  const [tableData] = useState([
+    { date: '2024-01-01', name: '张三', address: '北京市' },
+    { date: '2024-01-02', name: '李四', address: '上海市' }
+  ]);
+
+  return (
+    <div>
+      <h1>React 中使用 Vue 组件</h1>
+      
+      <section>
+        <h2>表格组件</h2>
+        <PyTable 
+          propData={tableData} 
+          loading={<div>加载中...</div>}  // 可选：加载占位
+        />
+      </section>
+
+      <section>
+        <h2>天气组件</h2>
+        <PyWeather loading={<div>加载中...</div>} />
+      </section>
+    </div>
+  );
+}
+
+export default MyComponent;
+```
+
+### 4. 组件参数
+
+#### PyTable
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| propData | any | undefined | 表格数据数组 |
+| loading | ReactNode | undefined | 组件加载时的占位内容 |
+
+```jsx
+<PyTable 
+  propData={[{ date: '2024-01-01', name: '张三' }]}
+  loading={<Spinner />}
+/>
+```
+
+#### PyWeather
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| propData | object | undefined | 可选配置对象 |
+| loading | ReactNode | undefined | 组件加载时的占位内容 |
+
+```jsx
+<PyWeather 
+  propData={{ city: '北京' }}
+  loading={<div>正在加载天气组件...</div>}
+/>
+```
+
+### 5. initStore 配置
+
+```javascript
+import { initStore } from 'py-test-component/react';
+
+// 异步调用，仅设置配置到组件库内部 store
+// 不返回 store 实例，外部无法读取
+await initStore({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com'
+});
+```
+
+**重要**：React 中的 `initStore` 是异步的，且不暴露任何 store 方法，配置仅供组件库内部使用。
+
+---
+
+## Store 使用原则
+
+**组件库的 store 完全内部化**：
+- ✅ 外部可以通过 `initStore` 设置配置
+- ❌ 外部无法读取 store 状态
+- ❌ 外部无法订阅 store 变化
+- ❌ 外部无法获取 store 实例
+
+**这样设计的好处**：
+1. 避免与外部工程的状态管理（Vuex、Redux、MobX 等）冲突
+2. 组件库内部可以自主管理状态
+3. 外部工程只需关注传入配置，无需关心组件库内部状态
+
+---
+
+## 本地开发测试
+
+### 使用 file: 协议引用本地包
+
+在测试项目的 `package.json` 中：
+
+```json
+{
+  "dependencies": {
+    "py-test-component": "file:../py-component"
+  }
+}
+```
+
+然后执行：
+
+```bash
+npm install
+```
+
+### 测试项目结构
+
+```
+my-vue2-components/
+├── py-component/       # 组件库源码
+├── vue-test/           # Vue 测试工程
+└── react-test/         # React 测试工程
+```
+
+---
+
+## 常见问题
+
+### Q: React 项目中组件加载很慢？
+
+A: 首次加载时需要动态下载和解析 `py-component.esm.js`（约 1.1MB）。建议：
+- 在生产环境使用 CDN 加速
+- 或预加载组件库：`initStore()` 提前调用
+
+### Q: 样式不生效？
+
+A: 
+- **Vue**: 确保引入了 `element-ui/lib/theme-chalk/index.css`
+- **React**: CSS 会自动注入，无需手动引入
+
+### Q: propData 可以传什么类型？
+
+A: 不限制类型，可以是：
+- 数组（PyTable 需要）
+- 对象（配置项）
+- 任意 JavaScript 值
+
+### Q: 如何监听 store 变化？
+
+A: **不支持**。store 完全内部化，外部无法监听。如需与外部通信，建议通过组件事件或回调函数。
+
+### Q: 如何读取 store 中的配置？
+
+A: **不支持**。store 仅供组件库内部使用，外部只能通过 `initStore` 设置，无法读取。
+
+---
+
+## 完整示例
+
+### Vue 完整示例
+
+```vue
+<!-- App.vue -->
+<template>
+  <div id="app">
+    <h1>Vue 使用 PyComponent</h1>
+    <PyTable :propData="users" />
+    <PyWeather />
+  </div>
+</template>
+
+<script>
+import { PyTable, PyWeather } from 'py-test-component/vue';
+
+export default {
+  components: { PyTable, PyWeather },
+  data() {
+    return {
+      users: [
+        { date: '2024-01', name: '张三', address: '北京' },
+        { date: '2024-02', name: '李四', address: '上海' }
+      ]
+    };
+  }
+};
+</script>
+```
+
+### React 完整示例
+
+```jsx
+// App.jsx
+import React, { useState } from 'react';
+import { PyTable, PyWeather } from 'py-test-component/react';
+
+export default function App() {
+  const [data] = useState([
+    { date: '2024-01', name: '张三', address: '北京' },
+    { date: '2024-02', name: '李四', address: '上海' }
+  ]);
+
+  return (
+    <div>
+      <h1>React 使用 PyComponent</h1>
+      <PyTable propData={data} loading={<p>加载中...</p>} />
+      <PyWeather loading={<p>加载中...</p>} />
+    </div>
+  );
+}
+```