4. 自定义Widget开发入门：Widget开发环境搭建、Widget结构（HTML/CSS/JS）、资源文件组织

自定义 Widget 是 ThingsBoard 数据可视化能力的核心扩展点。通过开发自定义 Widget，你可以将任何前端图表库、业务逻辑或交互模式嵌入仪表板。本章将系统讲解 Widget 的开发环境搭建、三文件结构（HTML/CSS/JS）以及资源文件的组织规范。

4.1 开发环境搭建

ThingsBoard 自定义 Widget 的开发不需要本地编译工具链，所有代码均在 ThingsBoard 平台内完成编辑和调试。但为了提升开发效率，建议按以下步骤准备环境：

4.2 Widget 结构：HTML / CSS / JS

每个自定义 Widget 由三个独立的代码文件组成，分别对应结构、样式和行为。ThingsBoard 在渲染 Widget 时，会按顺序加载这三个部分。

4.2.1 HTML 模板

HTML 部分定义 Widget 的 DOM 结构。ThingsBoard 使用 Angular 的模板语法，支持数据绑定和指令。所有数据变量通过 $scope 或 ctx（上下文对象）注入。

<!-- 示例：一个简单的时序值显示 Widget -->
<div class="my-widget-container">
  <div class="widget-header">
    <span>{{ctx.widgetTitle}}</span>
  </div>
  <div class="widget-body">
    <div class="value-display">
      <span class="value">{{ctx.value | number:2}}</span>
      <span class="unit">{{ctx.units}}</span>
    </div>
    <div class="timestamp">
      <span>{{ctx.date | date:'yyyy-MM-dd HH:mm:ss'}}</span>
    </div>
  </div>
</div>

4.2.2 CSS 样式

CSS 部分控制 Widget 的视觉呈现。ThingsBoard 会自动为每个 Widget 的根元素添加一个唯一的类名（如 .tb-widget-xxx），避免样式污染。建议所有样式都使用类选择器，并加上自定义前缀。

.my-widget-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 8px;
  padding: 16px;
  box-sizing: border-box;
}

.widget-header {
  color: #ffffff;
  font-size: 14px;
  font-weight: 600;
  margin-bottom: 12px;
  opacity: 0.9;
}

.value-display {
  flex: 1;
  display: flex;
  align-items: baseline;
  justify-content: center;
}

.value {
  font-size: 48px;
  font-weight: 700;
  color: #ffffff;
  line-height: 1;
}

.unit {
  font-size: 18px;
  color: rgba(255, 255, 255, 0.8);
  margin-left: 8px;
}

.timestamp {
  text-align: center;
  color: rgba(255, 255, 255, 0.6);
  font-size: 12px;
  margin-top: 8px;
}

4.2.3 JavaScript 逻辑

JavaScript 部分是 Widget 的核心，负责数据获取、处理、渲染和交互。ThingsBoard 提供丰富的 ctx（上下文）API，用于访问数据源、订阅遥测、设置参数等。

// 示例：Widget JavaScript 逻辑
self.onInit = function() {
  // 初始化：设置默认值、绑定事件
  ctx.$scope.widgetTitle = ctx.settings.widgetTitle || '默认标题';
  ctx.$scope.units = ctx.settings.units || '';
  ctx.$scope.value = 0;
  ctx.$scope.date = new Date();

  // 订阅数据更新
  ctx.subscription = ctx.telemetrySubscription.subscribe(
    function(data) {
      // data 包含最新的遥测数据
      if (data && data.length > 0) {
        var latest = data[data.length - 1];
        ctx.$scope.value = latest.value;
        ctx.$scope.date = latest.ts;
        ctx.$scope.$digest();  // 触发 Angular 脏检查更新视图
      }
    },
    function(error) {
      console.error('数据订阅失败:', error);
    }
  );
};

self.onDestroy = function() {
  // 清理：取消订阅、释放资源
  if (ctx.subscription) {
    ctx.subscription.unsubscribe();
  }
};

self.onResize = function() {
  // 响应式：当 Widget 尺寸变化时触发
  // 可用于重新绘制图表或调整布局
};

4.3 资源文件组织

当 Widget 需要引入外部库（如 Chart.js、D3.js、ECharts）或自定义资源文件时，必须通过 ThingsBoard 的资源管理器进行管理。资源文件分为三类：

资源文件的组织遵循以下规范：

1. 统一存放： 所有资源文件上传至 ThingsBoard 的 Resources 模块（主菜单 → Resources）。
2. 命名规则： 使用语义化命名，如 echarts-5.4.3.min.js、my-widget-theme.json。
3. 版本管理： 在文件名中包含版本号，避免缓存问题。
4. 引用方式： 在 Widget 的 JavaScript 代码中使用 ctx.$injector 或 ctx.loadResource() 动态加载。

// 动态加载外部资源示例
self.onInit = function() {
  // 加载 ECharts 库
  ctx.loadResource('echarts-5.4.3.min.js').then(function() {
    // 库加载完成后初始化图表
    var chartDom = ctx.$container[0].querySelector('.chart-container');
    var myChart = echarts.init(chartDom);
    // ... 配置图表
  }).catch(function(error) {
    console.error('资源加载失败:', error);
  });

  // 加载 JSON 配置文件
  ctx.loadResource('my-widget-theme.json').then(function(config) {
    ctx.$scope.themeConfig = config;
    ctx.$scope.$digest();
  });
};

4.4 Widget 文件结构总览

下图展示了自定义 Widget 的完整文件结构及其在 ThingsBoard 平台中的组织关系：

4.5 开发工作流总结

自定义 Widget 的开发遵循“编辑-预览-调试”的循环流程。以下是推荐的开发步骤：

1. 规划： 确定 Widget 类型（时序/最新值/控制/静态）和数据需求。
2. 搭建骨架： 在 Widget 编辑器中编写 HTML 结构，使用占位数据测试布局。
3. 美化样式： 编写 CSS，确保 Widget 在不同尺寸下响应式适配。
4. 注入逻辑： 编写 JavaScript，实现数据订阅、处理和交互。
5. 加载资源： 上传并引用外部库或配置文件。
6. 调试优化： 使用浏览器开发者工具检查错误、优化性能。
7. 保存发布： 将 Widget 保存到 Bundle 中，供仪表板使用。