# wordcloud

**Repository Path**: ghostgeek/wordcloud

## Basic Information

- **Project Name**: wordcloud
- **Description**: 词云图练手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 词云图生成器

一个基于 HTML5 Canvas 和 SVG 的词云图生成器，支持多种形状、颜色和自定义词库。

## 功能特性

- **零依赖** - 纯原生 JavaScript 实现，无外部库依赖
- **形状遮罩** - 支持上传图片作为词云形状
- **自定义词库** - 可添加、编辑、批量导入词语
- **灵活配置** - 支持字体、颜色、字号、旋转角度等设置
- **交互功能** - 点击词语显示弹窗查看详情
- **导出功能** - 支持导出 SVG 和 HTML 格式

## 快速开始

1. 在浏览器中打开 `index.html`
2. 选择形状图片（可选）
3. 添加或导入词语
4. 配置样式选项
5. 点击“生成词云图”
6. 可点击词语查看详情，或导出 SVG/HTML

## 使用方法

### 添加词语
- 点击"+ 添加词”按钮添加单个词语
- 点击“批量导入”批量导入词语

### 形状图片
- 点击上传区域或拖拽图片到上传区域
- 支持 PNG、JPEG、GIF 等常见格式

### 设置选项
- **背景色** - 设置词云背景颜色
- **字体** - 选择字体样式
- **最小/最大字号** - 调整词语大小范围
- **间距** - 设置词语之间的间距
- **旋转角度** - 选择词语旋转模式

### 交互功能
- **Hover** - 鼠标悬停时词语会放大
- **点击** - 点击词语会弹出详细信息（名称、权重、颜色）

### 导出功能
- **导出 SVG** - 下载 SVG 格式的词云图
- **导出 HTML** - 下载独立的 HTML 文件

## 项目结构

```
词云图/
├── index.html    # 主页面
├── wordcloud.js  # 词云核心库
├── style.css     # 样式文件
└── README.md     # 说明文档
```

## 浏览器兼容

- Chrome 4+
- Firefox 3+
- Safari 4+
- Edge 12+
- IE 9+

## API 文档

### 构造函数

```javascript
const cloud = new WordCloud();
```

创建词云实例。

### setWords(words)

批量设置词库，按权重降序排序。

```javascript
cloud.setWords([
  { text: 'JavaScript', weight: 100, color: '#f7df1e' },
  { text: 'SVG', weight: 80 },
  { text: '词云', weight: 60 }
]);
```

**参数：**
- `words` - 词数组，每项包含：
  - `text` (string) - 词文本
  - `weight` (number) - 权重值，影响字体大小
  - `color` (string, 可选) - 自定义颜色，不设置则随机

**返回值：** `this`（支持链式调用）

### addWord(text, weight, color)

添加单个词。

```javascript
cloud.addWord('新词', 50, '#3182ce');
```

**参数：**
- `text` (string) - 词文本
- `weight` (number) - 权重值
- `color` (string, 可选) - 自定义颜色

**返回值：** `this`（支持链式调用）

### clearWords()

清空所有词。

```javascript
cloud.clearWords();
```

**返回值：** `this`（支持链式调用）

### setShape(source)

设置词云形状掩码，支持图片元素、Canvas 或原始像素数据。

```javascript
// 从 img 元素加载
const img = new Image();
img.src = 'shape.png';
cloud.setShape(img);

// 从 Canvas 加载
const canvas = document.querySelector('canvas');
cloud.setShape(canvas);

// 从原始像素数据加载
cloud.setShape({
  width: 800,
  height: 500,
  data: imageData.data  // Uint8ClampedArray
});
```

**支持的来源：**
- `HTMLImageElement` - 从图片元素加载
- `HTMLCanvasElement` - 直接读取 Canvas 像素
- `Object` - `{ width, height, data }` 格式的原始数据

**返回值：** `this`（支持链式调用）

### setShapeFromUrl(url)

从 URL 加载形状图片，返回 Promise。

```javascript
cloud.setShapeFromUrl('shape.png')
  .then(() => cloud.generate())
  .catch(err => console.error(err));
```

**参数：**
- `url` (string) - 图片 URL

**返回值：** `Promise`

### setOptions(options)

设置配置选项。

```javascript
cloud.setOptions({
  minFontSize: 12,
  maxFontSize: 72,
  wordGap: 4,
  fontFamily: 'Microsoft YaHei',
  bgColor: '#ffffff',
  rotation: 'random'
});
```

**可用选项：**

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `minFontSize` | number | 12 | 最小字体大小 |
| `maxFontSize` | number | 72 | 最大字体大小 |
| `wordGap` | number | 0 | 词间距（像素） |
| `fontFamily` | string | 'Arial' | 字体系列 |
| `bgColor` | string | '#ffffff' | 背景颜色 |
| `rotation` | string\|number | 'slanted' | 旋转模式 |

**rotation 可选值：**
- `'slanted'` - 斜体角度（-70° 到 70° 之间的 10 个角度）
- `'random'` - 随机角度（0°、30°、45°、60°、90°）
- `0` / `45` / `90` - 固定角度

**返回值：** `this`（支持链式调用）

### setClickListener(fn)

设置词点击回调函数。

```javascript
cloud.setClickListener(function(wordObj, event) {
  console.log('点击词：' + wordObj.text);
  alert('名称：' + wordObj.text + '\n权重：' + wordObj.weight + '\n颜色：' + wordObj.color);
});
```

**参数：**
- `fn` (function) - 回调函数，签名：`function(wordObj, event)`

**wordObj 对象属性：**
- `text` (string) - 词文本
- `weight` (number) - 权重值
- `color` (string) - 颜色
- `x` (number) - x 坐标
- `y` (number) - y 坐标
- `fontSize` (number) - 字号
- `rotation` (number) - 旋转角度

**返回值：** `this`（支持链式调用）

### generate()

生成词云布局。

```javascript
const result = cloud.generate();
// result = { svg, placed, unplaced }
```

**返回值：**
- `svg` (string) - SVG 字符串
- `placed` (array) - 成功放置的词列表
- `unplaced` (array) - 未能放置的词列表

### renderTo(container)

直接渲染到 DOM 容器，并自动绑定点击事件。

```javascript
// 传入选择器
cloud.renderTo('#container');

// 或传入元素
cloud.renderTo(document.getElementById('container'));
```

**参数：**
- `container` (string\|Element) - 容器选择器或 DOM 元素

**返回值：** `{ svg, placed, unplaced }`

### getSVG()

获取 SVG 字符串，如果尚未生成则先执行 generate()。

```javascript
const svg = cloud.getSVG();
document.querySelector('#container').innerHTML = svg;
```

**返回值：** `string` - SVG 字符串

### exportSVG()

导出纯 SVG 字符串，与 `getSVG()` 等效。

```javascript
const svg = cloud.exportSVG();
// 可保存为 .svg 文件
```

**返回值：** `string` - SVG 字符串

### exportHTML()

导出独立的 HTML 文件字符串。

```javascript
const html = cloud.exportHTML();
// 可保存为 .html 文件
```

**返回值：** `string` - 完整 HTML 字符串

### bindClick(container)

将点击事件绑定到已渲染的词元素上（必须在 `renderTo()` 或手动注入 SVG 后调用）。

```javascript
cloud.bindClick('#container');
```

**参数：**
- `container` (string\|Element) - 容器选择器或 DOM 元素

**返回值：** `this`（支持链式调用）

## License

MIT