@beppla/tapas-ui 1.4.32 → 1.4.33

package/package/module/WordCloud/README.md

@@ -0,0 +1,308 @@
+# WordCloud 组件
+
+`WordCloud` 是一个多功能词云组件，支持传统词云和气泡词云两种展示模式，用于可视化文本数据的频率或重要性。
+
+## 功能特性
+
+### 🎨 两种展示模式
+
+- **Traditional（传统模式）**：经典的词云布局，文字紧密堆叠，根据权重调整字号
+- **Bubble（气泡模式）**：全新的圆形气泡布局，每个词在独立圆形内显示，更现代化的设计
+
+### 🌐 跨平台支持
+
+- **Web 端**
+  - 传统模式：使用 `react-wordcloud`（基于 D3）
+  - 气泡模式：使用 `d3-hierarchy` 的 pack 布局算法
+- **React Native 端**
+  - 传统模式：自定义 SVG 螺旋布局
+  - 气泡模式：自定义圆形打包算法
+
+### ✨ 核心功能
+
+- ✅ 自动根据数值调整大小（字号或气泡半径）
+- ✅ 支持自定义颜色方案
+- ✅ 文字旋转支持（传统模式）
+- ✅ Hashtag 前缀支持（气泡模式）
+- ✅ 响应式布局
+- ✅ 交互事件支持（点击、悬停）
+- ✅ 空数据状态处理
+
+## 安装依赖
+
+```bash
+# Web 端需要
+npm install react-wordcloud d3-hierarchy
+
+# React Native 端需要
+npm install react-native-svg
+```
+
+## 基本用法
+
+### 传统词云
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+const data = [
+  { text: 'React', value: 100 },
+  { text: 'TypeScript', value: 90 },
+  { text: 'JavaScript', value: 85 },
+  // ... more words
+];
+
+function App() {
+  return (
+    <WordCloud
+      words={data}
+      height={400}
+      colors={['#FF6B00', '#0066CC', '#00B894']}
+    />
+  );
+}
+```
+
+### 气泡词云
+
+```tsx
+import { WordCloud } from '@beppla/tapas-ui';
+
+const data = [
+  { text: 'Antioxidant', value: 100 },
+  { text: 'Vitamin C', value: 85 },
+  { text: 'Healthy', value: 70 },
+  // ... more words
+];
+
+function App() {
+  return (
+    <WordCloud
+      variant="bubble"
+      words={data}
+      height={600}
+      width={800}
+      showHashtag={true}
+      bubbleColors={{
+        primary: '#8B6F47',
+        secondary: '#D4C4B0',
+        text: '#FFFFFF',
+      }}
+      onBubbleClick={(word) => {
+        console.log('Clicked:', word.text);
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+### 公共属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `words` | `WordCloudData[]` | **必填** | 词云数据数组 |
+| `width` | `number` | `undefined` | 宽度（px），不设置则自适应 |
+| `height` | `number` | `400` | 高度（px） |
+| `variant` | `'traditional' \| 'bubble'` | `'traditional'` | 展示模式 |
+| `style` | `ViewStyle` | `undefined` | 容器样式 |
+| `testID` | `string` | `undefined` | 测试 ID |
+
+### 传统模式属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `colors` | `string[]` | 棕色系 | 文字颜色数组 |
+| `fontFamily` | `string` | `'Arial, sans-serif'` | 字体 |
+| `fontSizes` | `[number, number]` | `[14, 60]` | 字号范围 [最小, 最大] |
+| `rotate` | `number` | `0` | 旋转角度（0 表示不旋转） |
+| `spiral` | `'archimedean' \| 'rectangular'` | `'archimedean'` | 螺旋布局算法 |
+| `padding` | `number` | `2` | 词间距 |
+
+### 气泡模式属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `bubbleColors` | `BubbleColors` | 见下方 | 气泡颜色配置 |
+| `showHashtag` | `boolean` | `true` | 是否显示 # 前缀 |
+| `minBubbleSize` | `number` | `30` | 最小气泡半径（px） |
+| `maxBubbleSize` | `number` | `150` | 最大气泡半径（px） |
+| `bubblePadding` | `number` | `4` | 气泡间距（px） |
+| `fontFamily` | `string` | `'Arial, sans-serif'` | 字体 |
+| `onBubbleClick` | `(word: WordCloudData) => void` | `undefined` | 气泡点击回调 |
+
+### 数据类型
+
+```typescript
+interface WordCloudData {
+  text: string;      // 词文本
+  value: number;     // 权重/频率
+  color?: string;    // 自定义颜色（可选）
+}
+
+interface BubbleColors {
+  primary: string;   // 深色气泡（高权重）
+  secondary: string; // 浅色气泡（低权重）
+  text?: string;     // 文字颜色
+}
+```
+
+### 默认气泡颜色
+
+```typescript
+const DEFAULT_BUBBLE_COLORS = {
+  primary: '#8B6F47',    // 深棕色
+  secondary: '#D4C4B0',  // 浅米色
+  text: '#FFFFFF',       // 白色
+};
+```
+
+## 使用场景
+
+### 传统词云适用于
+
+- 📊 热门话题分析
+- 🔍 关键词提取展示
+- 📈 用户反馈词频统计
+- 🏷️ 标签云
+- 📝 文章摘要可视化
+
+### 气泡词云适用于
+
+- 🎯 产品特性展示
+- 💼 品牌关键词
+- 🌟 用户兴趣标签
+- 📱 移动端友好展示
+- 🎨 现代化 Dashboard
+
+## 高级示例
+
+### Figma 设计复刻
+
+完全复刻提供的 Figma 设计：
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={[
+    { text: 'Antioxidant', value: 100 },
+    { text: 'Anti-inflammatory', value: 95 },
+    { text: 'Vitamin C', value: 88 },
+    { text: 'Boost immune system', value: 85 },
+    { text: 'Dietary', value: 72 },
+    { text: 'Healthy', value: 70 },
+    { text: 'Super food', value: 68 },
+    { text: 'Veggie', value: 65 },
+    { text: 'Kale', value: 62 },
+    { text: 'Organic', value: 50 },
+  ]}
+  height={600}
+  width={1000}
+  showHashtag={true}
+  bubbleColors={{
+    primary: '#8B6F47',
+    secondary: '#D4C4B0',
+    text: '#FFFFFF',
+  }}
+  minBubbleSize={40}
+  maxBubbleSize={180}
+  bubblePadding={8}
+/>
+```
+
+### 自定义颜色方案
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={techWords}
+  bubbleColors={{
+    primary: '#61DAFB',    // React 蓝
+    secondary: '#3178C6',  // TypeScript 蓝
+    text: '#FFFFFF',
+  }}
+  showHashtag={false}
+/>
+```
+
+### 交互式气泡
+
+```tsx
+<WordCloud
+  variant="bubble"
+  words={words}
+  onBubbleClick={(word) => {
+    // 处理点击事件
+    console.log('Clicked:', word.text, word.value);
+    // 可以触发导航、弹窗等
+  }}
+/>
+```
+
+## 性能优化
+
+### 数据量建议
+
+- **传统模式**：推荐 10-50 个词
+- **气泡模式**：推荐 8-20 个词（更多词会导致气泡变小）
+
+### 优化提示
+
+```tsx
+// 1. 使用 useMemo 缓存数据
+const wordsData = useMemo(() => processWords(rawData), [rawData]);
+
+// 2. 控制数据量
+const topWords = words.slice(0, 20);
+
+// 3. 合理设置尺寸
+<WordCloud
+  words={topWords}
+  height={600}  // 气泡模式建议 >= 500
+  width={800}   // 气泡模式建议 >= 600
+/>
+```
+
+## 注意事项
+
+1. **依赖安装**：确保已安装对应平台的依赖库
+2. **容器尺寸**：气泡模式需要足够的空间（建议 width >= 600, height >= 500）
+3. **文字长度**：过长的文本会自动截断或缩小字号
+4. **浏览器兼容**：Web 端需要支持 SVG 的现代浏览器
+5. **性能考虑**：大数据量时建议只显示 Top N 的词
+
+## 浏览器/平台支持
+
+- ✅ Chrome / Edge (最新版)
+- ✅ Firefox (最新版)
+- ✅ Safari (最新版)
+- ✅ iOS (React Native)
+- ✅ Android (React Native)
+
+## Changelog
+
+### v1.4.32 (Latest)
+
+- ✨ 新增气泡词云（bubble variant）
+- ✨ 支持 Hashtag 前缀显示
+- ✨ 新增气泡点击事件
+- ✨ 支持自定义气泡颜色和大小
+- 📚 新增 6 个气泡词云 Story 示例
+- 🧪 新增气泡模式测试用例
+
+### v1.4.30 之前
+
+- ✅ 传统词云基础功能
+- ✅ Web 和 RN 跨平台支持
+- ✅ 自定义颜色和字号
+
+## 相关链接
+
+- [Storybook 示例](https://your-storybook-url.com)
+- [API 文档](https://your-api-docs-url.com)
+- [GitHub Issues](https://github.com/your-repo/issues)
+
+## License
+
+MIT © Beppla

package/package/module/WordCloud/WordCloud.js

@@ -0,0 +1,405 @@
+"use strict";
+
+/**
+ * WordCloud 组件
+ * 支持传统词云和气泡词云两种模式
+ * 
+ * 注意：本组件包含 Web 特定代码（SVG、div 等），因此禁用部分 RN lint 规则
+ */
+
+/* eslint-disable react-native/no-inline-styles */
+/* eslint-disable react-native/no-color-literals */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import React, { useMemo } from 'react';
+import { View, StyleSheet, Platform, Text as RNText } from 'react-native';
+
+// 动态导入依赖
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+let Svg, Text, G, Circle;
+let D3WordCloud, d3Hierarchy, d3Pack;
+if (Platform.OS === 'web') {
+  // Web 端使用 react-wordcloud 和 d3-hierarchy
+  try {
+    const wordcloud = require('react-wordcloud');
+    D3WordCloud = wordcloud.default || wordcloud;
+  } catch (e) {
+    // console.warn('react-wordcloud not available for Web', e);
+  }
+  try {
+    const d3 = require('d3-hierarchy');
+    d3Hierarchy = d3.hierarchy;
+    d3Pack = d3.pack;
+  } catch (e) {
+    // console.warn('d3-hierarchy not available for Web', e);
+  }
+} else {
+  // RN 端使用 react-native-svg
+  try {
+    const svg = require('react-native-svg');
+    Svg = svg.Svg;
+    Text = svg.Text;
+    G = svg.G;
+    Circle = svg.Circle;
+  } catch (e) {
+    // console.warn('react-native-svg not available', e);
+  }
+}
+const DEFAULT_COLORS = ['#8B4513',
+// Brown (like Trendy topics screenshot)
+'#A0522D', '#D2691E', '#CD853F', '#DEB887', '#F4A460', '#D2B48C', '#BC8F8F'];
+const DEFAULT_BUBBLE_COLORS = {
+  primary: '#8B6F47',
+  // 深棕色（参考 Figma 设计）
+  secondary: '#D4C4B0',
+  // 浅米色
+  text: '#FFFFFF' // 白色文字
+};
+export const WordCloud = ({
+  words,
+  width,
+  height = 400,
+  colors = DEFAULT_COLORS,
+  fontFamily = 'Arial, sans-serif',
+  fontSizes = [14, 60],
+  rotate = 0,
+  spiral = 'archimedean',
+  padding = 2,
+  style,
+  testID,
+  variant = 'traditional',
+  bubbleColors = DEFAULT_BUBBLE_COLORS,
+  showHashtag = true,
+  minBubbleSize = 30,
+  maxBubbleSize = 150,
+  bubblePadding = 4,
+  onBubbleClick
+}) => {
+  if (!words || words.length === 0) {
+    return /*#__PURE__*/_jsx(View, {
+      style: [styles.container, {
+        height
+      }, style],
+      children: /*#__PURE__*/_jsx(RNText, {
+        style: styles.emptyText,
+        children: "No words available"
+      })
+    });
+  }
+
+  // 气泡布局数据处理
+  const bubbleData = useMemo(() => {
+    if (variant !== 'bubble') return null;
+    const maxValue = Math.max(...words.map(w => w.value));
+    const minValue = Math.min(...words.map(w => w.value));
+    const valueRange = maxValue - minValue || 1;
+    return words.map((word, _index) => {
+      const normalized = (word.value - minValue) / valueRange;
+      const radius = minBubbleSize + normalized * (maxBubbleSize - minBubbleSize);
+
+      // 根据权重决定颜色（高于中位数使用 primary，否则使用 secondary）
+      const median = (maxValue + minValue) / 2;
+      const bubbleColor = word.color || (word.value >= median ? bubbleColors.primary : bubbleColors.secondary);
+      const textColor = bubbleColors.text || '#FFFFFF';
+
+      // 文字大小根据气泡大小自适应
+      const fontSize = Math.max(10, Math.min(18, radius * 0.25));
+      return {
+        ...word,
+        radius,
+        bubbleColor,
+        textColor,
+        fontSize,
+        displayText: showHashtag && !word.text.startsWith('#') ? `#${word.text}` : word.text
+      };
+    });
+  }, [words, variant, minBubbleSize, maxBubbleSize, bubbleColors, showHashtag]);
+
+  // 传统词云布局
+  if (variant === 'traditional') {
+    // Web 端使用 react-wordcloud
+    if (Platform.OS === 'web' && D3WordCloud) {
+      const wordCloudData = words.map(word => ({
+        text: word.text,
+        value: word.value
+      }));
+      const options = {
+        rotations: rotate === 0 ? 1 : 2,
+        rotationAngles: rotate === 0 ? [0, 0] : [-90, 0],
+        fontSizes,
+        fontFamily,
+        padding,
+        spiral,
+        scale: 'sqrt',
+        transitionDuration: 500
+      };
+      const callbacks = {
+        getWordColor: word => {
+          const index = words.findIndex(w => w.text === word.text);
+          if (index >= 0 && words[index] && words[index].color) {
+            return words[index].color || colors[index % colors.length];
+          }
+          return colors[Math.max(0, index) % colors.length];
+        },
+        getWordTooltip: word => `${word.text}: ${word.value}`
+      };
+      return /*#__PURE__*/_jsx(View, {
+        style: [styles.container, {
+          height,
+          width: width || '100%'
+        }, style],
+        testID: testID,
+        children: /*#__PURE__*/_jsx("div", {
+          style: {
+            width: '100%',
+            height: '100%'
+          },
+          children: /*#__PURE__*/_jsx(D3WordCloud, {
+            words: wordCloudData,
+            options: options,
+            callbacks: callbacks
+          })
+        })
+      });
+    }
+
+    // RN 端使用自定义 SVG 实现
+    if (Platform.OS !== 'web' && Svg && Text) {
+      // 简单的词云布局算法
+      const sortedWords = [...words].sort((a, b) => b.value - a.value);
+      const maxValue = Math.max(...words.map(w => w.value));
+      const minValue = Math.min(...words.map(w => w.value));
+      const viewWidth = width || 350;
+      const viewHeight = height;
+      const centerX = viewWidth / 2;
+      const centerY = viewHeight / 2;
+
+      // 计算字体大小
+      const getFontSize = value => {
+        const normalized = (value - minValue) / (maxValue - minValue || 1);
+        return fontSizes[0] + normalized * (fontSizes[1] - fontSizes[0]);
+      };
+
+      // 螺旋布局
+      const layoutWords = () => {
+        const positioned = [];
+        sortedWords.forEach((word, wordIndex) => {
+          const fontSize = getFontSize(word.value);
+          const colorIndex = wordIndex % colors.length;
+          const defaultColorIndex = wordIndex % DEFAULT_COLORS.length;
+          const color = word.color || colors[colorIndex] || DEFAULT_COLORS[defaultColorIndex] || '#8B4513';
+
+          // 简单的螺旋布局
+          const angle = wordIndex * 0.5;
+          const radius = Math.sqrt(wordIndex + 1) * 20;
+          const x = centerX + radius * Math.cos(angle);
+          const y = centerY + radius * Math.sin(angle);
+          positioned.push({
+            word,
+            x,
+            y,
+            fontSize,
+            color
+          });
+        });
+        return positioned;
+      };
+      const positionedWords = layoutWords();
+      return /*#__PURE__*/_jsx(View, {
+        style: [styles.container, {
+          height,
+          width: viewWidth
+        }, style],
+        testID: testID,
+        children: /*#__PURE__*/_jsx(Svg, {
+          width: viewWidth,
+          height: viewHeight,
+          children: /*#__PURE__*/_jsx(G, {
+            children: positionedWords.map((item, index) => /*#__PURE__*/_jsx(Text, {
+              x: item.x,
+              y: item.y,
+              fontSize: item.fontSize,
+              fill: item.color,
+              fontFamily: fontFamily,
+              textAnchor: "middle",
+              fontWeight: "bold",
+              children: item.word.text
+            }, index))
+          })
+        })
+      });
+    }
+  }
+
+  // 气泡布局模式
+  if (variant === 'bubble' && bubbleData) {
+    const viewWidth = width || 600;
+    const viewHeight = height;
+
+    // Web 端使用 D3 pack 布局
+    if (Platform.OS === 'web' && d3Hierarchy && d3Pack) {
+      const packLayout = d3Pack().size([viewWidth, viewHeight]).padding(bubblePadding);
+      const root = d3Hierarchy({
+        children: bubbleData
+      }).sum(d => d.radius * d.radius);
+      const nodes = packLayout(root).leaves();
+      return /*#__PURE__*/_jsx(View, {
+        style: [styles.container, {
+          height,
+          width: viewWidth
+        }, style],
+        testID: testID,
+        children: /*#__PURE__*/_jsx("svg", {
+          width: viewWidth,
+          height: viewHeight,
+          style: {
+            backgroundColor: 'transparent'
+          },
+          children: nodes.map((node, index) => {
+            const data = node.data;
+            return /*#__PURE__*/_jsxs("g", {
+              onClick: () => onBubbleClick?.(data),
+              children: [/*#__PURE__*/_jsx("circle", {
+                cx: node.x,
+                cy: node.y,
+                r: node.r,
+                fill: data.bubbleColor,
+                stroke: "none",
+                style: {
+                  cursor: onBubbleClick ? 'pointer' : 'default'
+                }
+              }), /*#__PURE__*/_jsx("text", {
+                x: node.x,
+                y: node.y,
+                textAnchor: "middle",
+                dominantBaseline: "middle",
+                fontSize: data.fontSize,
+                fill: data.textColor,
+                fontFamily: fontFamily,
+                fontWeight: "400",
+                style: {
+                  userSelect: 'none',
+                  pointerEvents: 'none',
+                  maxWidth: node.r * 1.8
+                },
+                children: data.displayText
+              })]
+            }, index);
+          })
+        })
+      });
+    }
+
+    // RN 端使用简化的圆形打包算法
+    if (Platform.OS !== 'web' && Svg && Circle && Text) {
+      // 简化的圆形打包布局算法
+      const layoutBubbles = () => {
+        const positioned = [];
+        const sortedData = [...bubbleData].sort((a, b) => b.radius - a.radius);
+        const centerX = viewWidth / 2;
+        const centerY = viewHeight / 2;
+        sortedData.forEach((data, index) => {
+          let x = 0;
+          let y = 0;
+          let attempts = 0;
+          const maxAttempts = 100;
+          if (index === 0) {
+            // 第一个气泡放在中心
+            x = centerX;
+            y = centerY;
+          } else {
+            // 后续气泡使用螺旋算法寻找位置
+            while (attempts < maxAttempts) {
+              const angle = attempts * 0.5;
+              const spiralRadius = Math.sqrt(attempts + 1) * (data.radius + bubblePadding);
+              x = centerX + spiralRadius * Math.cos(angle);
+              y = centerY + spiralRadius * Math.sin(angle);
+
+              // 检查是否与已有气泡重叠
+              const overlaps = positioned.some(p => {
+                const dx = x - p.x;
+                const dy = y - p.y;
+                const distance = Math.sqrt(dx * dx + dy * dy);
+                return distance < data.radius + p.r + bubblePadding;
+              });
+              if (!overlaps) {
+                break;
+              }
+              attempts++;
+            }
+
+            // 如果找不到合适位置，强制放置
+            if (attempts >= maxAttempts) {
+              x = centerX + (Math.random() * viewWidth * 0.3 - viewWidth * 0.15);
+              y = centerY + (Math.random() * viewHeight * 0.3 - viewHeight * 0.15);
+            }
+          }
+          positioned.push({
+            data,
+            x: x || 0,
+            y: y || 0,
+            r: data.radius
+          });
+        });
+        return positioned;
+      };
+      const positionedBubbles = layoutBubbles();
+      return /*#__PURE__*/_jsx(View, {
+        style: [styles.container, {
+          height,
+          width: viewWidth
+        }, style],
+        testID: testID,
+        children: /*#__PURE__*/_jsx(Svg, {
+          width: viewWidth,
+          height: viewHeight,
+          children: /*#__PURE__*/_jsx(G, {
+            children: positionedBubbles.map((bubble, index) => /*#__PURE__*/_jsxs(G, {
+              onPress: () => onBubbleClick?.(bubble.data),
+              children: [/*#__PURE__*/_jsx(Circle, {
+                cx: bubble.x,
+                cy: bubble.y,
+                r: bubble.r,
+                fill: bubble.data.bubbleColor,
+                stroke: "none"
+              }), /*#__PURE__*/_jsx(Text, {
+                x: bubble.x,
+                y: bubble.y,
+                fontSize: bubble.data.fontSize,
+                fill: bubble.data.textColor,
+                fontFamily: fontFamily,
+                textAnchor: "middle",
+                alignmentBaseline: "middle",
+                fontWeight: "400",
+                children: bubble.data.displayText
+              })]
+            }, index))
+          })
+        })
+      });
+    }
+  }
+
+  // 降级显示
+  return /*#__PURE__*/_jsx(View, {
+    style: [styles.container, {
+      height
+    }, style],
+    children: /*#__PURE__*/_jsx(RNText, {
+      style: styles.emptyText,
+      children: "WordCloud library not available"
+    })
+  });
+};
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: 'transparent',
+    justifyContent: 'center',
+    alignItems: 'center'
+  },
+  emptyText: {
+    textAlign: 'center',
+    color: '#999'
+  }
+});
+//# sourceMappingURL=WordCloud.js.map