開發應用程式的最佳作法 > 設計 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
如果您擁有可當地語系化的 STRING 內容，則會在此內容中列出它們。
例如，如果 TooltipLabel1 可當地語系化：
this.runtimeProperties = function () {
return {
'needsDataLoadingAndError': true,
'propertyAttributes': {
'TooltipLabel1': {'isLocalizable': true} }
}
};
• renderHtml() [必填] - 此函數會傳回執行時間在螢幕上放置的 HTML 片段。小器具的內容容器 (例如，div) 應該在其中指定小器具內容類別。指定類別之後，容器元素會附加至 DOM。容器可使用 jqElement 存取，並可在 jqElementId 中取得其 DOM 元素 ID。
• 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}() - 當執行時間需要內容值時，它會檢查以查看小器具是否實行函數，以取代並取得該內容的值。執行時間從小器具取得資料以填入服務呼叫參數時，系統會執行此操作。