可用于自定义 ThingWorx 小组件的函数
本部分将介绍可用于小组件的函数。
Mashup Builder 中的小组件生命周期
小组件在 Mashup Builder 中具有以下生命周期。在每个生命周期状态中，Mashup Builder 调用可用于小组件的以下函数：
• 已发现
小组件将在 index.html 中加载，并添加到小组件工具栏或选项板中。
|
函数
|
说明
|
|---|---|
|
widgetProperties()
|
获取混搭中每个小组件的信息。系统将检索显示名称和说明等信息。
|
|
widgetEvents()
|
获取每个小组件所显示的事件的相关信息。
|
|
widgetServices()
|
获取每个小组件所显示的服务的相关信息。
|
• 已创建
小组件会添加到混搭面板上。
|
函数
|
说明
|
|---|---|
|
afterload()
|
在已加载对象且从文件中恢复属性之后，但在显示对象之前调用。
|
• 已附加
小组件将被附加到工作区 DOM 元素。
|
函数
|
说明
|
|---|---|
|
renderHtml()
|
获取插入到混搭 DOM 元素中的 HTML 片段。
|
|
afterRender()
|
在将表示小组件的 HTML 片段插入到混搭 DOM 元素中，并将可用的元素 ID 分配给保存小组件内容的 DOM 元素之后调用。此后，DOM 元素准备就绪，可以进行操作。
|
• 已更新
小组件会在小组件属性窗口中调整大小或更新。
|
函数
|
说明
|
|---|---|
|
beforeSetProperty()
|
在更新小组件属性之前调用。
|
|
afterSetProperty()
|
在更新小组件属性之后调用。
|
• 已破坏
小组件会从混搭中删除。
|
函数
|
说明
|
|---|---|
|
beforeDestroy()
|
在移除小组件的 DOM 元素，且将小组件从其父项小组件分离并释放之前调用。您应释放在小组件生命周期内获取的资源，例如插件和事件处理程序。
|
属性包
属性包是一组名称值对。每对都是一个简单的值存储。ThingWorx 使用属性包作为混搭的结构持久化机制。
可用于小组件的 Mashup Builder API
在 Mashup Builder 上下文中，小组件可访问以下 API：
• this.jqElementId - 这是在 HTML 页面上显示小组件后，对象的 DOM 元素 ID。
• this.jqElement - 此为 jQuery 元素。
• this.getProperty(name) - 检索属性的名称。
• this.setProperty(name,value) - 如果在小组件中定义了 afterSetProperty()，则每次调用函数 afterSetProperty() 时都会调用此函数。
• this.updatedProperties() - 在小组件中更改属性时，应调用此函数。调用函数后，Mashup Builder 会更新小组件属性窗口。
• this.getInfotableMetadataForProperty(propertyName) - 获取绑定属性的信息表元数据。如果未绑定属性，则会返回 undefined。
• this.resetPropertyToDefaultValue(propertyName) - 将指定的属性重置为其默认值。
• this.removeBindingsFromPropertyAsTarget(propertyName) - 从指定的属性中移除目标数据绑定。
• this.removeBindingsFromPropertyAsSource(propertyName) - 从指定的属性中移除源数据绑定。
• this.isPropertyBoundAsTarget(propertyName) - 检查属性是否已作为目标进行绑定。您可以使用函数来确定属性是否已被设置或绑定。例如，以下示例将说明如何使用博客小组件中的 validate() 函数来确定属性是否已绑定：
this.validate = function () {
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
• this.isPropertyBoundAsSource(propertyName) - 检查属性是否已作为源进行绑定。您可以使用函数来确定属性是否已绑定到目标。例如，以下示例将说明如何使用复选框小组件中的 validate() 函数来确定属性是否已绑定：
this.validate = function () {
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
从 Mashup Builder 到小组件的回调
小组件上的以下函数由 Mashup Builder 调用，以修改小组件的行为。
• widgetProperties() [必填]- 返回用于定义小组件属性的 JSON 结构。
必需的属性包括：
◦ name - 显示在小组件工具栏中的小组件的名称。
可选属性包括：
|
属性
|
说明
|
|---|---|
|
description
|
小组件说明，可用作其工具提示。
|
|
iconImage
|
小组件图标或图像的文件名。
|
|
category
|
用于指定在哪些类别下能够使用小组件的字符串数组。
例如，“常用”、“图表”、“数据”、“容器”等。这使用户能够按类别类型筛选小组件。
|
|
isResizable
|
指定是否可以调整小组件的大小。
|
|
defaultBindingTargetProperty
|
应该用作数据或事件绑定目标的属性的名称。
|
|
borderWidth
|
如果小组件具有边界，则将此属性设置为边界的宽度。该属性可帮助您在开发期间和运行时确保完美像素设计。
例如，假设某个小组件在运行时的大小应为 10X10 像素，且边界大小为 1 个像素。在设计时，小组件的大小应为 8X8 像素，以便在设计时处理添加 1 个像素的问题。这会将边界置于小组件内，并保证小组件属性中的宽度和高度能够准确。
|
|
isContainer
|
指定小组件的实例是否可以是其他小组件实例的容器。有效值为 true 和 false。属性的默认值为 false。
|
|
customEditor
|
应该用来设置和编辑小组件配置的自定义编辑器对话框的名称。在小组件项目中，创建一个名称为 TW.IDE.Dialogs.<name> 的对话框。
|
|
customEditorMenuText
|
显示在小组件快捷菜单中的文本。此外，此文本还可显示为 ThingWorx Composer 中小组件的工具提示。例如，“配置栅格列”。
|
|
allowPositioning
|
检查小组件是否可放置在面板上。有效值为 true 和 false。属性的默认值为 true。
|
|
supportsLabel
|
指定小组件是否支持标签属性。有效值为 true 和 false。属性的默认值为 false。
当设置为 true 时，小组件将显示标签属性。此属性用于创建在 ThingWorx Composer 中以及运行时显示在小组件旁边的文本标签。
|
|
supportsAutoResize
|
指定小组件是否自动支持调整大小。有效值为 true 和 false。属性的默认值为 false。
如果设置为 true，则可以将小组件放置在响应式容器 (例如，列、行、响应式选项卡和响应式混搭) 中。
|
|
特性
|
小组件的 JSON 对象集合，用于描述在将小组件添加到混搭时可修改的小组件属性。这些属性显示在 Mashup Builder 的属性窗口中，其中将每个对象的名称用作属性名称。相应的属性可控制属性值的设置方式。
例如：
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
可为每个属性对象指定以下属性：
|
属性
|
说明
|
||||
|---|---|---|---|---|---|
|
description
|
用于工具提示的小组件的说明。
|
||||
|
baseType
|
小组件的基本类型。如果基本类型值为 FIELDNAME，则小组件属性窗口将显示信息表中可用的字段列表。这些字段将根据基本类型限制绑定到 sourcePropertyName 值。
其他特殊基本类型为：
• STATEDEFINITION - 选择状态定义。
• STYLEDEFINITION - 选择样式定义。
• RENDERERWITHSTATE - 将显示一个对话框，可让您从中选择数据呈现器和状态格式。
• STATEFORMATTING - 将显示一个对话框，使您能够选择固定样式或基于状态的样式。
• VOCABULARYNAME - 在运行时选择数据标记词汇。
|
||||
|
mustImplement
|
如果基本类型为 THINGNAME，并且您指定了 mustImplement 属性，则 Mashup Builder 会将对话框限制为仅打开那些实现指定 EntityType 和 EntityName 的弹出窗口。Mashup Builder 调用函数 QueryImplementingThings，以验证所传递值的类型是否为 EntityType，并检查是否实现了 EntityName。
例如：
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
如果将小组件的基本类型设置为 RENDERERWITHFORMAT，则属性将指定用于配置的信息表属性。
|
||||
|
sourcePropertyName
|
如果将小组件的基本类型设置为 FIELDNAME，则属性将检查用于配置的信息表属性。
|
||||
|
baseTypeRestriction
|
如果指定了此属性，则该值将用于限制 FIELDNAME 下拉列表中的可用字段。
|
||||
|
tagType
|
如果基本类型设置为 TAGS，则属性将指定标记类型。有效值为 DataTags，即默认值或 ModelTags。
|
||||
|
defaultValue
|
用于设置属性的默认值。默认值为 undefined。
|
||||
|
isBindingSource
|
指定属性是否为数据绑定源。有效值为 true 和 false。属性的默认值为 fasle。
|
||||
|
isBindingTarget
|
指定属性是否为数据绑定目标。有效值为 true 和 false。属性的默认值为 fasle。
|
||||
|
IsEditable
|
指定属性在 ThingWorx Composer 中是否处于可编辑状态。有效值为 true，即默认值和 false。
|
||||
|
isVisible
|
指定属性在属性窗口中是否可见。有效值为 true 和 false。属性的默认值为 true。
|
||||
|
isLocalizable
|
指定属性是否可本地化。当基本类型设置为字符串时，需要此属性。有效值为 true 和 false。
|
||||
|
selectOptions
|
值或显示文本结构的数组。
例如：
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer 检查属性是否为数据绑定源。有效值为 true 和 false。
如果将属性值设置为 true，但未绑定属性，则 ThingWorx Composer 会生成一个项列表，您必须完成这些项才能保存混搭。
|
||||
|
warnIfNotBoundAsTarget
|
Composer 检查属性是否为数据绑定目标。有效值为 true 和 false。
如果将属性值设置为 true，但未绑定属性，则 ThingWorx Composer 会生成一个项列表，您必须完成这些项才能保存混搭。
|
• afterLoad() [可选] - 在已加载对象且从文件中恢复属性之后，但在 HTML 页面上显示对象之前调用此函数。
• renderHtml() [必填] - 该函数返回 ThingWorx Composer 在屏幕上放置的 HTML 片段。小组件的内容容器 (例如，div) 中应指定小组件内容类。此后，容器元素将被附加到 DOM 中。可以使用 jqElement 来访问容器，其 DOM 元素 ID 在 jqElementId 中提供。
• widgetEvents() [可选] - 事件的集合；每个事件都可以具有以下属性：
◦ warnIfNotBound - Composer 将检查属性是否已绑定。有效值为 true 和 false。
如果将属性值设置为 true，但未绑定属性，则 ThingWorx Composer 会生成一个项列表，您必须完成这些项才能保存混搭。
• widgetServices() [可选] - 服务的集合；每个服务都可以具有以下属性：
◦ warnIfNotBound - Composer 将检查属性是否已绑定。有效值为 true 和 false。
如果将属性值设置为 true，但未绑定属性，则 ThingWorx Composer 会生成一个项列表，您必须完成这些项才能保存混搭。
• afterRender() [可选] - 在将 HTML 片段插入 DOM 中之后调用此函数。
• beforeDestroy() [可选] - 在移除小组件的 DOM 元素，且将小组件从其父小组件分离并释放之前调用此函数。应释放在小组件生命周期内获取的资源，例如插件、事件处理程序等。
• beforeSetProperty(name,value) [可选] [仅限 Mashup Builder - 运行时除外] - 在 ThingWorx Composer 中对任何属性进行更新之前调用此函数。在提交新属性值之前，您可以对其执行验证。如果验证失败，则可以返回一个消息字符串，以通知用户输入无效。新属性值未提交。如果在验证期间未返回任何内容，则假定值有效。
• afterSetProperty(name,value) [可选] [仅限 Mashup Builder - 运行时除外] - 在 ThingWorx Composer 中对任何属性进行更新之后调用此函数。如果将值指定为 true，则在值发生更改后，小组件将再次显示在 ThingWorx Composer 中。
• afterAddBindingSource(bindingInfo) [可选] - 只要将数据绑定到小组件，就会调用此函数。bindingInfo 中的唯一字段为 targetProperty，该字段为属性名称，并且处于绑定状态。
• validate() [可选] - 当 ThingWorx Composer 刷新其待办清单时，将会调用此函数。调用将返回一个由结果对象组成的数组：
◦ severity - 此为可选属性。检测到的问题的严重程度。
◦ message - 此为必需属性。消息文本可能包含一个或多个预定义的标记，例如 {target-id}。消息将被替换为超链接，用户可通过该超链接来导航并选择生成消息的特定小组件。
例如：
this.validate = function () {
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}