自定义小组件
- Last UpdatedJun 29, 2026
- 3 minute read
客户端控件和 OMI 应用程序仅支持桌面端，在 Web 客户端中无法运行。自定义小组件提供跨平台解决方案，使您能够一次开发，然后在 InTouch 和 OMI 应用程序中跨 Web 和桌面环境使用它们。
先决条件
在开始之前，请确保已安装以下软件：
-
Node.js（24.15.0 或更高版本）和 npm（11.12.1 或更高版本）：用于安装依赖项和构建小组件包。请从 nodejs.org 下载。
-
文本编辑器：用于编辑小组件文件。建议使用 Visual Studio Code。
本节介绍如何在 InTouch 和 OMI 应用程序中创建、构建和使用自定义小组件。请按照以下步骤操作：
-
第 1 步：创建和修改自定义小组件
-
第 2 步：更新项目文件
-
第 3 步：在 .wjson 文件中定义小组件属性和方法
-
第 4 步：构建小组件包
-
第 5 步：导入并使用小组件
第 1 步：创建和修改自定义小组件
入门时，可在 C:\ProgramData\AVEVA\Widgets\SampleWidget 获取示例小组件。
Templates 文件夹包含用于创建新小组件的基础文件。在常规小组件开发过程中，请勿修改这些模板文件。
-
在 WidgetCreator 目录 (C:\ProgramData\AVEVA\Widgets\WidgetCreator) 中打开终端。
-
运行以下命令以创建新小组件
npm run create-widget MyWidgetName。其中，MyWidgetName 是新小组件的名称。
-
导航到新创建的小组件文件夹：cd MyWidgetName。
-
在 Visual Studio Code 中打开新小组件文件夹以进行更改。
第 2 步：更新项目文件
您可以自定义以下项目文件来构建小组件：
-
index.html：用于根据需要修改 HTML 结构。此必备文件是主入口点，在打开小组件时首先加载。请勿重命名此文件。
-
src/*.css：用于自定义视觉样式。
-
src/*.js：用于实现小组件逻辑。
注意：默认的 CSS 和 JavaScript 文件名以示例小组件命名。您可以根据需要重命名这些文件。
第 3 步：在 .wjson 文件中定义小组件属性和方法
.wjson 文件充当小组件与 InTouch 和 OMI 应用程序之间的契约。它定义了小组件向平台公开的属性。
了解 .wjson 结构
.wjson 文件包括以下关键字段：
-
version：指定小组件的版本。
-
width 和 height：定义小组件初次添加时的缺省大小。
-
events：当前尚未实现，但计划在后续版本中提供。
-
properties：定义小组件向平台公开的属性。每个属性必须从"0"开始依次编号，然后是"1"、"2"，依此类推。
注意：这些字段为必备字段，不得删除，因为它们是小组件正常运行所必需的。
可配置的属性字段
您可以为每个小组件属性配置以下字段：
-
Name：指定在 InTouch 和 OMI 中显示的小组件属性名称。名称最多可包含 32 个字符。
-
Type：定义属性的数据类型。支持的属性类型包括布尔型、双精度型、经过时间、浮点型、整型、字符串型、时间型和历史摘要型。
-
Value：设置分配给小组件属性的默认值。
-
Desc：提供小组件属性的描述。此字段支持多种语言，以提升本地化和可用性。
以下示例展示了两个属性。要添加新属性，请复制完整的 JSON 条目，并更新序号以及名称、类型和其他相关字段。
{
"version": 0,
"width": 500,
"height": 500,
"events": {},
"properties": {
"0": {
"name": "Counter",
"type": "integer",
"value": 0,
"desc": {
"1033": "Counter value",
"1036": "Valeur du compteur",
"1031": "Zählerwert",
"1041": "カウンター値",
"2052": "计数器值"
}
},
"1": {
"name": "Label",
"type": "string",
"value": "Count:",
"desc": {
"1033": "Display label",
"1036": "Étiquette d'affichage",
"1031": "Anzeigebeschriftung",
"1041": "表示ラベル",
"2052": "显示标签"
}
}
}
}
在 JavaScript 中使用小组件属性
在 .wjson 文件中定义属性后，您可以在 JavaScript 中使用 cwidget 访问它们。
监听属性更改
要检测小组件属性的更改，请使用以下模式（将 'Counter' 替换为实际属性名称）：
cwidget.on('Counter', callbackFn);
callbackFn：每当属性值更改时执行的函数。它可用于更新 UI 或触发其他逻辑。
示例小组件中的示例：
在 SampleWidget.js 中，当 'Counter' 属性更改时，会触发 _onCounterCshanged() 函数以更新显示：
cwidget.on('Counter', _onCounterChanged);
function _onCounterChanged() {
document.getElementById('counter').innerText = cwidget.Counter;
}
设置属性值
要为小组件属性赋新值，请使用以下语法：
cwidget.Counter = nextValue;
nextValue：存储要赋给属性的值。它应与属性的数据类型匹配（例如，整型属性使用数字，或字符串型属性使用字符串）。
示例小组件中的示例：
在 SampleWidget.js 中，增量按钮更新 Counter 属性。这会自动触发回调并更新所有绑定控件：
function _increment() {
const current = Number.parseInt(cwidget.Counter, 10) || 0;
cwidget.Counter = current + 1;
}
在 JavaScript 中绑定可调用方法（可选）
要允许 InTouch 和 OMI 应用程序调用小组件中的方法，可以通过将小组件类方法绑定到 window 对象上的函数来公开这些方法。
下面是一个示例（将 SampleWidget、Decrement、_decrement 和 Counter 替换为您自己的类和方法名）：
class SampleWidget {
constructor() {
window.Decrement = this._decrement.bind(this);
}
_decrement(args) {
var number = JSON.parse(args[0]);
const current = Number.parseInt(cwidget.Counter, 10) || 0;
const delta = Number.parseInt(number, 10) || 0;
cwidget.Counter = current - delta;
_onCounterChanged();
}
}
这将创建一个名为“Decrement”的可调用函数，在导入小组件后，可以在工业图形动作脚本中使用该函数。
第 4 步：构建小组件包
完成开发后，按照以下步骤构建小组件并生成可部署包：
-
在小组件文件夹 (C:\ProgramData\AVEVA\Widgets\WidgetCreator\MyWidgetName) 中打开终端。
-
运行构建命令 npm run build。
这会在 dist 文件夹中生成一个 .cwp 包。
第 5 步：导入并使用小组件
小组件构建完成后，您可以将其导入并在应用程序中使用。按照以下步骤将小组件导入 InTouch 应用程序并绑定其属性：
为 InTouch WindowViewer 导入和嵌入小组件
-
在应用程序中打开 WindowMaker。
-
转到文件 > 导入 > 可视化 > HTML5 小组件。
-
选择第 4 步中生成的 .cwp 文件。
-
打开“图形编辑器”，然后从工业图形 > 小组件中嵌入该小组件。
为 System Platform IDE 导入和嵌入小组件
-
打开 Galaxy。
-
转到主页选项卡，然后选择导入。
-
选择 Web 小组件。
-
选择第 4 步中生成的 .cwp 文件。
导入后，小组件会出现在图形编辑器工具箱中，您可以将其拖放到图形上。
绑定自定义属性
通过将小组件属性绑定到自定义属性，可以实现小组件与应用程序中其它控件之间的双向同步。
设置绑定
-
在应用程序中创建自定义属性。在本示例中，我们使用 cp_value。
-
将小组件属性绑定到自定义属性。在小组件属性网格中，将 Counter 小组件属性链接到 cp_value。
双向绑定
绑定设置完成后，更改就会自动在两个方向上同步：
-
从小组件到应用程序：当小组件更新其属性时（例如，cwidget.Counter = newValue），cp_value 自定义属性将会更新，并且所有绑定的控件（如文本框）都会反映新值。
-
从应用程序到小组件：当您在文本框中输入值时，cp_value 会随之更改。此更改会触发向 cwidget.on() 注册的回调函数，从而使小组件能够做出响应并保持 UI 同步。
从脚本中调用小组件方法
如果您已经在小组件中定义了可调用方法（请参阅第 3 步：在 JavaScript 中绑定可调用方法），则可以从图形脚本编辑器中调用小组件方法。
在本示例中，创建一个带有动作脚本动画的按钮，以便在单击该按钮时触发先前在 JavaScript 中绑定的 Decrement 方法。
dim args [1] as object;
args[1]=5;
SampleWidget1.ExecuteFunctionAsync("Decrement",args);
例如，要调用 Decrement 函数：
此脚本会在您的小组件实例上调用 Decrement 方法，并传入值 5。点击该按钮时，小组件的计数器会减少 5。
其中
-
SampleWidget1 是图形上小组件实例的名称。
-
ExecuteFunctionAsync 是用于异步调用小组件函数的方法。
-
Decrement 是映射到 JavaScript 绑定窗口的方法名称。Decrement this._decrement.bind (this)。
-
Args 是一个对象数组，用于存储传递给小组件方法的参数。数组索引应从 [1] 开始（而不是 [0]）。
请将 SampleWidget1 替换为实际的小组件名称，并根据需要调整方法名称和参数。
您的自定义小组件现已完全集成，可以随时使用。