开发应用程序的最佳做法 > 设计 ThingWorx 应用程序的用户体验 > ThingWorx 应用程序中的小组件 > 创建自定义 ThingWorx 小组件 > 可用于自定义 ThingWorx 小组件的运行时函数
可用于自定义 ThingWorx 小组件的运行时函数
本部分介绍了在运行时适用于小组件的函数。
运行时的小组件生命周期
• 首次创建小组件时，运行时将通过调用 runtimeProperties() 函数来获取任何声明的属性。
有关详细信息，请参阅 从运行时到小组件的回调部分。
• 保存在混搭定义中的属性值将加载到您的对象中，而不调用任何函数。
• 加载小组件后但在将其呈现到屏幕之前，运行时将调用函数 renderHtml()。在此函数中，您将返回对象的 HTML。运行时会将此函数返回的 HTML 呈现在 DOM 中的适当位置。
• 将 HTML 添加到 DOM 后，系统将调用函数 afterRender()。如果需要，您可以执行 jQuery 绑定。此时，您可以引用实际 DOM 元素。例如，使用以下代码来引用 DOM 元素：
// note that this is a jQuery object
var widgetElement = this.domElement;
* 
运行时会更改 DOM 元素的 ID。建议始终使用 jQuery 对象 this.domElementId 来获取 DOM 元素的 ID。
• 如果已定义可绑定的事件，则可以触发此事件，如以下示例所示：
var widgetElement = this.domElement;
// change ‘Clicked’ to be your event name
// you defined in your runtimeProperties
widgetElement.triggerHandler('Clicked');
• 如果将任何属性绑定为数据目标，则系统会调用函数 updateProperty()。如果更改的属性会影响 DOM，则应直接更新 DOM。绑定数据时，大多数情况下 DOM 会发生更改。
• 如果您将属性定义为数据源并将它们绑定，则可以调用函数 getProperty_{propertyName}()。如果未定义此函数，则运行时将从属性包中获取值。
可用于小组件的运行时 API
运行时上下文中的小组件可以访问以下 API：
• this.jqElementId - 此为在 HTML 页面上呈现小组件后对象的 DOM 元素 ID。
• this.jqElement - 此为 jQuery 元素。
• this.getProperty(name) - 获取属性的名称。
• this.setProperty(name,value) - 设置属性的名称和值。
• this.updateSelection(propertyName,selectedRowIndices) - 在小组件更改所选行的属性时调用此函数。这些行中的数据已绑定到其中。例如，在回调中，如果已定义一个事件，例如 onSelectStateChanged()，则系统会调用 API this.updateSelection(propertyName,selectedRowIndices)，并更新从属于选定行的所有小组件。
从运行时到小组件的回调
小组件的以下函数由运行时调用：
• runtimeProperties() [可选] - 将返回用于定义小组件属性的 JSON 结构。
可选属性包括：
属性
说明
isContainer
指定小组件的实例是否可以是其他小组件实例的容器。有效值为 true 和 false。属性的默认值为 fasle。
needsDataLoadingAndError
有效值为 true 和 false。属性的默认值为 fasle。如果希望小组件在未接收到数据时显示 25% 的标准不透明度，请将此属性设置为 true。如果在检索数据时出错，则小组件会变为红色。
borderWidth
如果小组件具有边界，则将此属性设置为边界的宽度。此属性可帮助您确保开发和运行时期间的完美像素设计。
supportsAutoResize
指定小组件是否自动支持调整大小。有效值为 true 和 false。
propertyAttributes
如果您具有可本地化的字符串属性，会在此属性中将其列出。
例如，如果 TooltipLabel1 可本地化：
this.runtimeProperties = function () {
return {
'needsDataLoadingAndError': true,
'propertyAttributes': {
'TooltipLabel1': {'isLocalizable': true} }
}
};
• renderHtml() [必填] - 此函数会返回运行时在屏幕上放置的 HTML 片段。例如，小组件的内容容器 div 应在其中指定小组件-内容类。指定此类后，系统会将容器元素附加到 DOM。此容器可以使用 jqElement 来访问，且其 DOM 元素 ID 在 jqElementId 中提供。
• afterRender() [可选] - 在将小组件 HTML 片段插入 DOM 中后，系统会调用此函数。使用 this.domElementId 可获取 DOM 元素 ID。使用 this.jqElement 元素可获取 jQuery DOM 元素。
• beforeDestroy() [可选但强烈建议] - 在将小组件从屏幕上移除时会调用此函数。利用此函数，您可以：
◦ 取消任何绑定
◦ 清除含有 .data() 的任何数据集
◦ 销毁任何第三方存储库或插件，调用其析构函数等。
◦ 通过将所有变量设置为 null，释放您分配或保留在闭包中的任何内存
◦ 您无需销毁小组件内的 DOM 元素，因为它们会由运行时销毁
• resize(width,height) [可选 - 仅当声明 supportsAutoResize: true 时有用] - 当调整小组件大小时，会可调用此函数。
某些小组件不需要处理这种情况。例如，如果小组件和 CSS 的元素会自动缩放。
但是，大多数小组件需要在小组件的大小发生变化时进行处理。
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) - 当选定行由与其绑定且具有指定属性的数据源修改时，系统会调用此函数。selectedRows 是实际数据的数组，而 selectedRowIndices 是选定行的索引数组。
* 
您必须定义此功能才能获得完整的 selectedRows 事件功能，而无需绑定列表或栅格小组件。
• serviceInvoked(serviceName) - 在触发您定义的服务时，系统会调用此函数。
• updateProperty(updatePropertyInfo) - updatePropertyInfo 是具有下列 JSON 结构的对象：
{
DataShape: metadata for the rows returned
ActualDataRows: actual Data Rows
SourceProperty: SourceProperty
TargetProperty: TargetProperty
RawSinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
SinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
converted to the defined baseType of the
target property [not implemented yet],
SelectedRowIndices: an array of selected row indices
IsBoundToSelectedRows: a Boolean letting you know if this
is bound to SelectedRows
}
对于每个数据绑定，每次更改源数据时，系统都会调用小组件的 updateProperty()。应检查 updatePropertyInfo.TargetProperty，以确定应更新小组件的哪些方面。
有关小组件，请参阅以下示例：
this.updateProperty = function (updatePropertyInfo) {
// get the img inside our widget in the DOM
var widgetElement = this.jqElement.find('img');
// if we're bound to a field in selected rows
// and there are no selected rows, we'd overwrite the
// default value if we didn't check here
if (updatePropertyInfo.RawSinglePropertyValue !==
undefined) {
// see which TargetProperty is updated
if (updatePropertyInfo.TargetProperty === 'sourceurl') {
// SourceUrl updated - update the <img src=
this.setProperty('sourceurl',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("src",
updatePropertyInfo.SinglePropertyValue);
} else if (updatePropertyInfo.TargetProperty ===
'alternatetext') {

// AlternateText updated - update the <img alt=
this.setProperty('alternatetext',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("alt",
updatePropertyInfo.SinglePropertyValue);
}
}
};
在小组件对象中设置此属性的本地副本。这样可确保运行时系统能够从属性包中获取此属性。
或者，您也可以提供自定义 getProperty_{propertyName} 方法并以其他方式存储值。
• getProperty_{propertyName}() - 当运行时需要属性值时，它会检查您的小组件是否实现了一个函数来覆盖和获取此属性的值。当运行时获取小组件数据以填充服务调用的参数时，将执行此操作。