py-test-component 2.0.6 → 2.0.8

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>
+  );
+}
+```