@beppla/tapas-ui 1.4.33 → 1.4.34

package/components/DEPENDENCY_WARNINGS.md

@@ -0,0 +1,242 @@
+# 依赖警告处理指南
+
+## 常见警告及解决方案
+
+### 1. `Module not found: Can't resolve 'd3-hierarchy'`
+
+**原因：** WordCloud 的气泡模式需要 `d3-hierarchy`，但该依赖被标记为可选，不会自动安装。
+
+**解决方案：**
+
+#### 方案 1：安装依赖（推荐）
+
+如果你需要使用气泡词云功能：
+
+```bash
+npm install d3-hierarchy
+# 或
+yarn add d3-hierarchy
+```
+
+#### 方案 2：忽略警告
+
+如果你只使用传统词云，可以忽略此警告，或在 webpack 配置中屏蔽：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+#### 方案 3：条件导入
+
+在代码中使用时动态检测：
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+// 只使用传统模式，不会触发 d3-hierarchy 加载
+<WordCloud
+  variant="traditional"  // 默认值
+  words={data}
+/>
+
+// 如果使用气泡模式，确保已安装 d3-hierarchy
+<WordCloud
+  variant="bubble"  // 需要 d3-hierarchy
+  words={data}
+/>
+```
+
+---
+
+### 2. `Module not found: NestedPieChart` 路径错误
+
+**错误示例：**
+
+```tsx
+// ❌ 错误：不要使用相对路径访问 node_modules 内部文件
+const m = require("../../../../../node_modules/@beppla/tapas-ui/commonjs/PieChart/NestedPieChart");
+```
+
+**原因：** 使用了错误的导入路径。
+
+**正确导入方式：**
+
+```tsx
+// ✅ 正确：从包的根路径导入
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 或者从子路径导入（如果需要）
+import { NestedPieChart } from '@beppla/tapas-ui/PieChart';
+```
+
+**如果需要动态导入：**
+
+```tsx
+// ✅ 正确的动态导入
+let NestedPieChart;
+try {
+  if (Platform.OS === 'web') {
+    // 从包的正确导出路径导入
+    const module = await import('@beppla/tapas-ui');
+    NestedPieChart = module.NestedPieChart;
+  }
+} catch (error) {
+  console.warn('NestedPieChart not available');
+}
+```
+
+---
+
+## 完整依赖列表
+
+### WordCloud 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `react-wordcloud` | 传统词云 | Web | 可选 |
+| `d3-cloud` | 传统词云 | Web | 可选 |
+| `d3-hierarchy` | 气泡词云 | Web | 可选 |
+| `react-native-svg` | 所有模式 | RN | 可选 |
+
+### PieChart / NestedPieChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg` | 图表渲染 | RN | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+### LineChart / BarChart / ComboChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+---
+
+## 按需安装策略
+
+### 策略 1：最小安装
+
+只使用基础组件（不包含图表）：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+```
+
+### 策略 2：Web 图表
+
+使用 Web 端图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install recharts d3-hierarchy react-wordcloud
+```
+
+### 策略 3：RN 图表
+
+使用 React Native 图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install react-native-svg react-native-svg-charts
+```
+
+### 策略 4：全平台图表（推荐）
+
+同时支持 Web 和 RN：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+
+# Web 依赖
+npm install recharts d3-hierarchy react-wordcloud d3-cloud
+
+# RN 依赖
+npm install react-native-svg react-native-svg-charts
+```
+
+---
+
+## 生产环境优化
+
+### Tree Shaking
+
+确保你的打包工具支持 tree-shaking，未使用的组件不会被打包：
+
+```js
+// 只导入需要的组件
+import { WordCloud, NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 只有 WordCloud 和 NestedPieChart 会被打包
+// ✅ 未使用的组件（如 BarChart）不会被打包
+```
+
+### 按需加载
+
+对于大型应用，可以使用动态导入：
+
+```tsx
+// 懒加载气泡词云
+const BubbleCloudPage = lazy(() => 
+  import('./pages/BubbleCloud').then(module => ({
+    default: module.BubbleCloudPage
+  }))
+);
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不将这些依赖设为必需依赖？
+
+**A:** 这些依赖较大（如 `recharts` ~500KB），并且不是所有用户都需要所有功能。将它们设为可选依赖可以：
+- 减小默认包体积
+- 让用户按需安装
+- 支持更灵活的使用场景
+
+### Q: 警告会影响应用运行吗？
+
+**A:** 不会。这些警告只是提示缺少可选依赖，不影响：
+- 已安装依赖的功能正常使用
+- 应用的其他部分
+- 构建和部署流程
+
+### Q: 如何确认依赖是否正确安装？
+
+**A:** 运行以下命令：
+
+```bash
+# 检查 d3-hierarchy
+npm list d3-hierarchy
+
+# 检查 recharts
+npm list recharts
+
+# 检查所有 @beppla/tapas-ui 依赖
+npm list --depth=0 | grep -E "d3|recharts|svg"
+```
+
+---
+
+## 获取帮助
+
+如果遇到其他依赖问题：
+
+1. 查看 [完整文档](https://github.com/your-repo/tapas-ui)
+2. 搜索 [GitHub Issues](https://github.com/your-repo/tapas-ui/issues)
+3. 提交新的 Issue 并附上：
+   - 错误信息
+   - 你的 package.json
+   - 使用的平台（Web / RN）
+   - 组件代码示例

package/components/WordCloud/README.md

@@ -30,15 +30,86 @@
 
 ## 安装依赖
 
+### 必需依赖
+
+```bash
+npm install react react-native
+```
+
+### WordCloud 可选依赖
+
+根据你的使用场景安装对应的依赖：
+
+#### 传统词云（Web 端）
+
 ```bash
 # Web 端需要
-npm install react-wordcloud d3-hierarchy
+npm install react-wordcloud d3-cloud
+```
+
+#### 气泡词云（Web 端）
+
+```bash
+# Web 端气泡模式需要
+npm install d3-hierarchy
+```
+
+#### React Native 端
+
+```bash
+# RN 端需要（两种模式都需要）
+npm install react-native-svg
+```
+
+### 完整安装（推荐）
+
+如果你想使用所有功能，建议一次性安装：
+
+```bash
+# Web 端完整依赖
+npm install react-wordcloud d3-cloud d3-hierarchy
 
-# React Native 端需要
+# React Native 端依赖
 npm install react-native-svg
 ```
 
-## 基本用法
+### ⚠️ 依赖说明
+
+- 这些依赖被标记为 `optional`，不会自动安装
+- 如果缺少依赖，组件会优雅降级并显示提示信息
+- **警告处理**：如果你看到 `Module not found: Can't resolve 'd3-hierarchy'` 警告，这是正常的。你可以：
+  - **方案 1（推荐）**：安装 `d3-hierarchy` 以使用气泡词云功能
+  - **方案 2**：如果只使用传统词云，可以忽略这个警告（不影响使用）
+  - **方案 3**：在 webpack 配置中添加 `IgnorePlugin` 忽略警告（见下方）
+
+### 忽略警告（Webpack）
+
+如果你不需要气泡词云功能，可以在 webpack 配置中忽略警告：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+或者使用 `externals`：
+
+```js
+// webpack.config.js
+module.exports = {
+  externals: {
+    'd3-hierarchy': 'd3-hierarchy',
+  },
+};
+```
+
+---
 
 ### 传统词云
 

package/package/commonjs/DEPENDENCY_WARNINGS.md

@@ -0,0 +1,242 @@
+# 依赖警告处理指南
+
+## 常见警告及解决方案
+
+### 1. `Module not found: Can't resolve 'd3-hierarchy'`
+
+**原因：** WordCloud 的气泡模式需要 `d3-hierarchy`，但该依赖被标记为可选，不会自动安装。
+
+**解决方案：**
+
+#### 方案 1：安装依赖（推荐）
+
+如果你需要使用气泡词云功能：
+
+```bash
+npm install d3-hierarchy
+# 或
+yarn add d3-hierarchy
+```
+
+#### 方案 2：忽略警告
+
+如果你只使用传统词云，可以忽略此警告，或在 webpack 配置中屏蔽：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+#### 方案 3：条件导入
+
+在代码中使用时动态检测：
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+// 只使用传统模式，不会触发 d3-hierarchy 加载
+<WordCloud
+  variant="traditional"  // 默认值
+  words={data}
+/>
+
+// 如果使用气泡模式，确保已安装 d3-hierarchy
+<WordCloud
+  variant="bubble"  // 需要 d3-hierarchy
+  words={data}
+/>
+```
+
+---
+
+### 2. `Module not found: NestedPieChart` 路径错误
+
+**错误示例：**
+
+```tsx
+// ❌ 错误：不要使用相对路径访问 node_modules 内部文件
+const m = require("../../../../../node_modules/@beppla/tapas-ui/commonjs/PieChart/NestedPieChart");
+```
+
+**原因：** 使用了错误的导入路径。
+
+**正确导入方式：**
+
+```tsx
+// ✅ 正确：从包的根路径导入
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 或者从子路径导入（如果需要）
+import { NestedPieChart } from '@beppla/tapas-ui/PieChart';
+```
+
+**如果需要动态导入：**
+
+```tsx
+// ✅ 正确的动态导入
+let NestedPieChart;
+try {
+  if (Platform.OS === 'web') {
+    // 从包的正确导出路径导入
+    const module = await import('@beppla/tapas-ui');
+    NestedPieChart = module.NestedPieChart;
+  }
+} catch (error) {
+  console.warn('NestedPieChart not available');
+}
+```
+
+---
+
+## 完整依赖列表
+
+### WordCloud 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `react-wordcloud` | 传统词云 | Web | 可选 |
+| `d3-cloud` | 传统词云 | Web | 可选 |
+| `d3-hierarchy` | 气泡词云 | Web | 可选 |
+| `react-native-svg` | 所有模式 | RN | 可选 |
+
+### PieChart / NestedPieChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg` | 图表渲染 | RN | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+### LineChart / BarChart / ComboChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+---
+
+## 按需安装策略
+
+### 策略 1：最小安装
+
+只使用基础组件（不包含图表）：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+```
+
+### 策略 2：Web 图表
+
+使用 Web 端图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install recharts d3-hierarchy react-wordcloud
+```
+
+### 策略 3：RN 图表
+
+使用 React Native 图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install react-native-svg react-native-svg-charts
+```
+
+### 策略 4：全平台图表（推荐）
+
+同时支持 Web 和 RN：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+
+# Web 依赖
+npm install recharts d3-hierarchy react-wordcloud d3-cloud
+
+# RN 依赖
+npm install react-native-svg react-native-svg-charts
+```
+
+---
+
+## 生产环境优化
+
+### Tree Shaking
+
+确保你的打包工具支持 tree-shaking，未使用的组件不会被打包：
+
+```js
+// 只导入需要的组件
+import { WordCloud, NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 只有 WordCloud 和 NestedPieChart 会被打包
+// ✅ 未使用的组件（如 BarChart）不会被打包
+```
+
+### 按需加载
+
+对于大型应用，可以使用动态导入：
+
+```tsx
+// 懒加载气泡词云
+const BubbleCloudPage = lazy(() => 
+  import('./pages/BubbleCloud').then(module => ({
+    default: module.BubbleCloudPage
+  }))
+);
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不将这些依赖设为必需依赖？
+
+**A:** 这些依赖较大（如 `recharts` ~500KB），并且不是所有用户都需要所有功能。将它们设为可选依赖可以：
+- 减小默认包体积
+- 让用户按需安装
+- 支持更灵活的使用场景
+
+### Q: 警告会影响应用运行吗？
+
+**A:** 不会。这些警告只是提示缺少可选依赖，不影响：
+- 已安装依赖的功能正常使用
+- 应用的其他部分
+- 构建和部署流程
+
+### Q: 如何确认依赖是否正确安装？
+
+**A:** 运行以下命令：
+
+```bash
+# 检查 d3-hierarchy
+npm list d3-hierarchy
+
+# 检查 recharts
+npm list recharts
+
+# 检查所有 @beppla/tapas-ui 依赖
+npm list --depth=0 | grep -E "d3|recharts|svg"
+```
+
+---
+
+## 获取帮助
+
+如果遇到其他依赖问题：
+
+1. 查看 [完整文档](https://github.com/your-repo/tapas-ui)
+2. 搜索 [GitHub Issues](https://github.com/your-repo/tapas-ui/issues)
+3. 提交新的 Issue 并附上：
+   - 错误信息
+   - 你的 package.json
+   - 使用的平台（Web / RN）
+   - 组件代码示例

package/package/commonjs/WordCloud/README.md

@@ -30,15 +30,86 @@
 
 ## 安装依赖
 
+### 必需依赖
+
+```bash
+npm install react react-native
+```
+
+### WordCloud 可选依赖
+
+根据你的使用场景安装对应的依赖：
+
+#### 传统词云（Web 端）
+
 ```bash
 # Web 端需要
-npm install react-wordcloud d3-hierarchy
+npm install react-wordcloud d3-cloud
+```
+
+#### 气泡词云（Web 端）
+
+```bash
+# Web 端气泡模式需要
+npm install d3-hierarchy
+```
+
+#### React Native 端
+
+```bash
+# RN 端需要（两种模式都需要）
+npm install react-native-svg
+```
+
+### 完整安装（推荐）
+
+如果你想使用所有功能，建议一次性安装：
+
+```bash
+# Web 端完整依赖
+npm install react-wordcloud d3-cloud d3-hierarchy
 
-# React Native 端需要
+# React Native 端依赖
 npm install react-native-svg
 ```
 
-## 基本用法
+### ⚠️ 依赖说明
+
+- 这些依赖被标记为 `optional`，不会自动安装
+- 如果缺少依赖，组件会优雅降级并显示提示信息
+- **警告处理**：如果你看到 `Module not found: Can't resolve 'd3-hierarchy'` 警告，这是正常的。你可以：
+  - **方案 1（推荐）**：安装 `d3-hierarchy` 以使用气泡词云功能
+  - **方案 2**：如果只使用传统词云，可以忽略这个警告（不影响使用）
+  - **方案 3**：在 webpack 配置中添加 `IgnorePlugin` 忽略警告（见下方）
+
+### 忽略警告（Webpack）
+
+如果你不需要气泡词云功能，可以在 webpack 配置中忽略警告：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+或者使用 `externals`：
+
+```js
+// webpack.config.js
+module.exports = {
+  externals: {
+    'd3-hierarchy': 'd3-hierarchy',
+  },
+};
+```
+
+---
 
 ### 传统词云
 

package/package/module/DEPENDENCY_WARNINGS.md

@@ -0,0 +1,242 @@
+# 依赖警告处理指南
+
+## 常见警告及解决方案
+
+### 1. `Module not found: Can't resolve 'd3-hierarchy'`
+
+**原因：** WordCloud 的气泡模式需要 `d3-hierarchy`，但该依赖被标记为可选，不会自动安装。
+
+**解决方案：**
+
+#### 方案 1：安装依赖（推荐）
+
+如果你需要使用气泡词云功能：
+
+```bash
+npm install d3-hierarchy
+# 或
+yarn add d3-hierarchy
+```
+
+#### 方案 2：忽略警告
+
+如果你只使用传统词云，可以忽略此警告，或在 webpack 配置中屏蔽：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+#### 方案 3：条件导入
+
+在代码中使用时动态检测：
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+// 只使用传统模式，不会触发 d3-hierarchy 加载
+<WordCloud
+  variant="traditional"  // 默认值
+  words={data}
+/>
+
+// 如果使用气泡模式，确保已安装 d3-hierarchy
+<WordCloud
+  variant="bubble"  // 需要 d3-hierarchy
+  words={data}
+/>
+```
+
+---
+
+### 2. `Module not found: NestedPieChart` 路径错误
+
+**错误示例：**
+
+```tsx
+// ❌ 错误：不要使用相对路径访问 node_modules 内部文件
+const m = require("../../../../../node_modules/@beppla/tapas-ui/commonjs/PieChart/NestedPieChart");
+```
+
+**原因：** 使用了错误的导入路径。
+
+**正确导入方式：**
+
+```tsx
+// ✅ 正确：从包的根路径导入
+import { NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 或者从子路径导入（如果需要）
+import { NestedPieChart } from '@beppla/tapas-ui/PieChart';
+```
+
+**如果需要动态导入：**
+
+```tsx
+// ✅ 正确的动态导入
+let NestedPieChart;
+try {
+  if (Platform.OS === 'web') {
+    // 从包的正确导出路径导入
+    const module = await import('@beppla/tapas-ui');
+    NestedPieChart = module.NestedPieChart;
+  }
+} catch (error) {
+  console.warn('NestedPieChart not available');
+}
+```
+
+---
+
+## 完整依赖列表
+
+### WordCloud 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `react-wordcloud` | 传统词云 | Web | 可选 |
+| `d3-cloud` | 传统词云 | Web | 可选 |
+| `d3-hierarchy` | 气泡词云 | Web | 可选 |
+| `react-native-svg` | 所有模式 | RN | 可选 |
+
+### PieChart / NestedPieChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg` | 图表渲染 | RN | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+### LineChart / BarChart / ComboChart 组件
+
+| 依赖 | 用途 | 平台 | 是否必需 |
+|------|------|------|----------|
+| `recharts` | 图表渲染 | Web | 可选 |
+| `react-native-svg-charts` | 图表渲染 | RN | 可选 |
+
+---
+
+## 按需安装策略
+
+### 策略 1：最小安装
+
+只使用基础组件（不包含图表）：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+```
+
+### 策略 2：Web 图表
+
+使用 Web 端图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install recharts d3-hierarchy react-wordcloud
+```
+
+### 策略 3：RN 图表
+
+使用 React Native 图表组件：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+npm install react-native-svg react-native-svg-charts
+```
+
+### 策略 4：全平台图表（推荐）
+
+同时支持 Web 和 RN：
+
+```bash
+npm install @beppla/tapas-ui react react-native
+
+# Web 依赖
+npm install recharts d3-hierarchy react-wordcloud d3-cloud
+
+# RN 依赖
+npm install react-native-svg react-native-svg-charts
+```
+
+---
+
+## 生产环境优化
+
+### Tree Shaking
+
+确保你的打包工具支持 tree-shaking，未使用的组件不会被打包：
+
+```js
+// 只导入需要的组件
+import { WordCloud, NestedPieChart } from '@beppla/tapas-ui';
+
+// ✅ 只有 WordCloud 和 NestedPieChart 会被打包
+// ✅ 未使用的组件（如 BarChart）不会被打包
+```
+
+### 按需加载
+
+对于大型应用，可以使用动态导入：
+
+```tsx
+// 懒加载气泡词云
+const BubbleCloudPage = lazy(() => 
+  import('./pages/BubbleCloud').then(module => ({
+    default: module.BubbleCloudPage
+  }))
+);
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么不将这些依赖设为必需依赖？
+
+**A:** 这些依赖较大（如 `recharts` ~500KB），并且不是所有用户都需要所有功能。将它们设为可选依赖可以：
+- 减小默认包体积
+- 让用户按需安装
+- 支持更灵活的使用场景
+
+### Q: 警告会影响应用运行吗？
+
+**A:** 不会。这些警告只是提示缺少可选依赖，不影响：
+- 已安装依赖的功能正常使用
+- 应用的其他部分
+- 构建和部署流程
+
+### Q: 如何确认依赖是否正确安装？
+
+**A:** 运行以下命令：
+
+```bash
+# 检查 d3-hierarchy
+npm list d3-hierarchy
+
+# 检查 recharts
+npm list recharts
+
+# 检查所有 @beppla/tapas-ui 依赖
+npm list --depth=0 | grep -E "d3|recharts|svg"
+```
+
+---
+
+## 获取帮助
+
+如果遇到其他依赖问题：
+
+1. 查看 [完整文档](https://github.com/your-repo/tapas-ui)
+2. 搜索 [GitHub Issues](https://github.com/your-repo/tapas-ui/issues)
+3. 提交新的 Issue 并附上：
+   - 错误信息
+   - 你的 package.json
+   - 使用的平台（Web / RN）
+   - 组件代码示例

package/package/module/WordCloud/README.md

@@ -30,15 +30,86 @@
 
 ## 安装依赖
 
+### 必需依赖
+
+```bash
+npm install react react-native
+```
+
+### WordCloud 可选依赖
+
+根据你的使用场景安装对应的依赖：
+
+#### 传统词云（Web 端）
+
 ```bash
 # Web 端需要
-npm install react-wordcloud d3-hierarchy
+npm install react-wordcloud d3-cloud
+```
+
+#### 气泡词云（Web 端）
+
+```bash
+# Web 端气泡模式需要
+npm install d3-hierarchy
+```
+
+#### React Native 端
+
+```bash
+# RN 端需要（两种模式都需要）
+npm install react-native-svg
+```
+
+### 完整安装（推荐）
+
+如果你想使用所有功能，建议一次性安装：
+
+```bash
+# Web 端完整依赖
+npm install react-wordcloud d3-cloud d3-hierarchy
 
-# React Native 端需要
+# React Native 端依赖
 npm install react-native-svg
 ```
 
-## 基本用法
+### ⚠️ 依赖说明
+
+- 这些依赖被标记为 `optional`，不会自动安装
+- 如果缺少依赖，组件会优雅降级并显示提示信息
+- **警告处理**：如果你看到 `Module not found: Can't resolve 'd3-hierarchy'` 警告，这是正常的。你可以：
+  - **方案 1（推荐）**：安装 `d3-hierarchy` 以使用气泡词云功能
+  - **方案 2**：如果只使用传统词云，可以忽略这个警告（不影响使用）
+  - **方案 3**：在 webpack 配置中添加 `IgnorePlugin` 忽略警告（见下方）
+
+### 忽略警告（Webpack）
+
+如果你不需要气泡词云功能，可以在 webpack 配置中忽略警告：
+
+```js
+// webpack.config.js
+module.exports = {
+  plugins: [
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^d3-hierarchy$/,
+      contextRegExp: /@beppla\/tapas-ui/,
+    }),
+  ],
+};
+```
+
+或者使用 `externals`：
+
+```js
+// webpack.config.js
+module.exports = {
+  externals: {
+    'd3-hierarchy': 'd3-hierarchy',
+  },
+};
+```
+
+---
 
 ### 传统词云
 

package/package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beppla/tapas-ui",
-  "version": "1.4.33",
+  "version": "1.4.34",
   "description": "Tapas UI Component Library - A comprehensive React Native component library with Expo support",
   "main": "./commonjs/index.js",
   "module": "./module/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beppla/tapas-ui",
-  "version": "1.4.33",
+  "version": "1.4.34",
   "main": "package/commonjs/index.js",
   "module": "package/module/index.js",
   "types": "package/typescript/index.d.ts",