# WaterfallWidget.js 文档

本文档为 `waterfallwidget.js` 文件提供详细说明，涵盖了 `waterfallwidget` 类的功能、用法和配置选项。该类用于创建频谱图和瀑布图可视化工具，广泛应用于信号处理和频谱分析领域。

## 概述

`waterfallwidget` 是一个功能强大的 JavaScript 类，用于在网页中绘制频谱图和瀑布图。它支持实时数据更新、频率缩放、用户交互、信号标注等多种功能，适用于无线电信号分析、频谱监控等场景。该类基于 Konva.js 库实现绘图功能，并提供了丰富的配置选项和事件处理机制。

## 初始化

要使用 `waterfallwidget`，需要通过构造函数创建一个实例，并传入容器 ID 和配置选项。以下是构造函数的定义：

```javascript
function waterfallwidget(id, options)
```

- **id**：字符串，指定容器的 DOM ID，用于渲染瀑布图。
- **options**：对象，包含各种配置选项，用于自定义瀑布图的行为和外观。

### 配置选项

以下是常用的配置选项及其默认值：

- **min_db**：最小分贝值，默认为 -200。
- **max_db**：最大分贝值，默认为 0。
- **min_freq**：最小频率值，默认为 0。
- **max_freq**：最大频率值，默认为 40000。
- **showSpectrogramAvg**：是否显示频谱平均值，默认为 false。
- **showSpectrogramMin**：是否显示频谱最小值，默认为 false。
- **showSpectrogramMax**：是否显示频谱最大值，默认为 false。
- **showPeakMarker**：是否显示峰值标记，默认为 false。
- **allowRunMode**：运行模式，0 表示侦察模式，1 表示实时模式，默认为 0。
- **disableZoom**：是否禁用缩放功能，默认为 false。
- **wfFreqPointLable**：是否启用频点标注，默认为 false。
- **bg_color**：背景颜色，默认为 '#37384B'。
- **fore_color**：前景颜色，默认为 '#CCCCFF'。
- **wave_color**：波形颜色，默认为 '#4BF3A7'。

更多配置选项请参见代码中的构造函数部分。

### 初始化示例

```javascript
var widget = new waterfallwidget('container', {
  min_db: -150,
  max_db: 0,
  min_freq: 50000000,
  max_freq: 100000000,
  showPeakMarker: true,
  allowRunMode: 1
});
widget.init();
```

## 主要方法

`waterfallwidget` 类提供了大量方法，用于数据处理、绘图和用户交互。以下是一些关键方法：

### addData(d, time)

添加新数据并更新瀑布图和频谱图。

- **d**：数组，包含信号强度数据。
- **time**：字符串，可选，数据的时间戳。

### drawWaterFall(bins)

绘制瀑布图的一行数据。

- **bins**：数组，包含信号强度数据。

### setFreqZoom(start, end)

设置频率缩放范围。

- **start**：数字，起始频率。
- **end**：数字，结束频率。

### changeDBRange(min_db, max_db, force)

更改分贝范围。

- **min_db**：数字，最小分贝值。
- **max_db**：数字，最大分贝值。
- **force**：布尔值，是否强制更新，默认为 false。

### drawAllSpectrogram(bins)

绘制完整的频谱图，包括峰值标记、最大/最小保持等。

- **bins**：数组，包含信号强度数据。

### setAdjCenter(freq, fireEvent)

设置调整中心频率。

- **freq**：数字，中心频率。
- **fireEvent**：布尔值，是否触发事件，默认为 false。

更多方法请参见代码中的详细实现。

## 属性

`waterfallwidget` 类包含大量属性，用于控制瀑布图的状态和外观。以下是一些重要属性：

- **min_db**：最小分贝值。
- **max_db**：最大分贝值。
- **freq_start**：当前显示的起始频率。
- **freq_end**：当前显示的结束频率。
- **showSpectrogramAvg**：是否显示频谱平均值。
- **showPeakMarker**：是否显示峰值标记。
- **adj_start**：调整起始频率。
- **adj_end**：调整结束频率。
- **bg_color**：背景颜色。
- **wave_color**：波形颜色。

## 事件处理

`waterfallwidget` 支持多种事件，允许开发者响应用户交互和状态变化。以下是一些常用事件：

- **zoom-change**：频率缩放变化时触发。
- **pointer-change**：指针位置变化时触发。
- **adj-change**：调整范围变化时触发。
- **label-change**：标签选择变化时触发。
- **context-click**：右键菜单点击时触发。

### 事件绑定示例

```javascript
widget.on('zoom-change', function(event) {
  console.log('Zoom changed to:', event.start, event.end);
});
```

## 用户交互

`waterfallwidget` 支持丰富的用户交互功能，包括：

- **频率缩放**：通过鼠标滚轮或拖动选择区域进行缩放。
- **调整范围**：在实时模式下，可以拖动调整频率范围。
- **峰值标记**：显示信号峰值并标注频率和强度。
- **右键菜单**：提供上下文菜单，支持多种操作如侦察、数据采集等。
- **频点标注**：允许用户添加和编辑频率点标注。

## 绘图逻辑

`waterfallwidget` 将绘图区域分为频谱图和瀑布图两部分：

- **频谱图**：显示当前信号的强度分布，支持平均值、最大值、最小值等多种显示模式。
- **瀑布图**：随时间滚动显示历史信号数据，使用颜色映射表示信号强度。

绘图使用 Konva.js 库实现，通过多层 canvas 叠加实现复杂的视觉效果。

## 使用示例

以下是一个完整的示例，展示如何初始化和使用 `waterfallwidget`：

```javascript
// 创建瀑布图实例
var widget = new waterfallwidget('waterfall-container', {
  min_db: -150,
  max_db: 0,
  min_freq: 50000000,
  max_freq: 100000000,
  showPeakMarker: true,
  showSpectrogramMax: true,
  allowRunMode: 0
});

// 初始化
widget.init();

// 添加数据
setInterval(function() {
  var data = Array.from({length: 2000}, () => Math.random() * (-50 + 150) - 150);
  widget.addData(data, new Date().toLocaleTimeString());
}, 1000);

// 监听缩放事件
widget.on('zoom-change', function(event) {
  console.log('Frequency range:', event.start, 'to', event.end);
});
```

## 注意事项

- **性能考虑**：对于大数据量和高频率更新，建议优化数据处理逻辑，避免频繁重绘。
- **浏览器兼容性**：依赖 Konva.js 库，确保在支持 HTML5 Canvas 的现代浏览器中使用。
- **配置选项**：初始化时需仔细配置频率和分贝范围，以适应具体的信号分析需求。
- **事件处理**：事件监听器应妥善管理，避免内存泄漏。

以上是 `waterfallwidget.js` 的完整文档，希望对您的使用和开发有所帮助。