Xrm.Page.ui 控制項 (用戶端參考)

 

發佈日期： 2016年11月

適用對象： Dynamics CRM 2015

control 物件提供變更控制項的展示或行為以及識別對應屬性的方法。

您可以使用下列集合存取控制項：Xrm.Page.ui.控制項、Xrm.Page.ui Section.控制項 或 Xrm.Page.data.entity Attribute.控制項。Xrm.Page.getControl 方法是存取 Xrm.Page.ui.controls.get 的捷徑方法。

本主題中的語法範例示範使用 Xrm.Page.getControl 方法來存取控制項。 是哪個控制項則視傳遞至方法的引數而定。 存取單一控制項的 args 參數必須是控制項或索引的名稱。

當表單在頁首中顯示商務程序流程控制項時，將會為商務程序流程中顯示的每個屬性新增額外的控制項。 這些控制項會有類似下列範例的唯一名稱：header_process_<attribute name>。

備註

商務程序流程的使用中階段的控制項才可透過此方式依名稱存取。

表單頁首顯示的控制項是可存取的，並且有類似下列的唯一名稱：header_<attribute name>。

對於繫結至屬性的控制項，通常會透過 Xrm.Page.data.entity Attribute.控制項 集合存取控制項。

控制項屬性及方法

• 已停用
  使用 getDisabled 和 setDisabled 方法，偵測狀態和啟用或停用控制項。

• getAttribute
  取得控制項繫結至的屬性。

• getControlType
  取得控制項類型的相關資訊。

• getName
  取得控制項的名稱。

• getParent
  取得控制項所在的區段物件。

• 知識庫控制項方法
  這些方法僅適用於 Microsoft Dynamics CRM Online 組織與 Parature 整合時可用的知識庫搜尋控制項。 這些方法在 Microsoft Dynamics CRM Online 2015 更新 1 引入。

  如需這些控制項的詳細資訊，請參閱 Parature 知識庫搜尋控制項 (用戶端參考)。

• 標籤
  使用 getLabel 和 setLabel 方法，取得或變更控制項的標籤。

• 查詢控制項方法及事件
  使用 addCustomFilter、addCustomView、getDefaultView 和 setDefaultView 方法，在使用者設定查詢控制項值時，控制向使用者顯示可從中選擇的結果。

  您可以使用 addPreSearch 和 removePreSearch 方法，新增或移除 PreSearch 事件 的事件處理常式。

• 通知
  使用 setNotification 和 clearNotification 方法，顯示和移除提供給使用者關於控制項的通知。

• OptionSet 控制項方法
  使用 addOption、clearOptions 和 removeOption 方法，修改顯示在 OptionSet 控制中的選項。

• ShowTime
  使用 setShowTime 指定日期控制項是否應顯示日期的時間部分，以及使用 getShowTime 判斷日期的時間部分目前是否顯示。

• 子格控制項方法
  對於使用 CRM Online 2015 更新 1 的組織，有新功能可使用子格控制項。其他資訊：Grid 物件和方法 (用戶端參考)

  對於其他組織，refresh 方法是唯一可用於子格控制項的唯一方法。 這個方法將重新整理子格中顯示的資料。

• 可見
  使用 getVisible 和 setVisible 方法，判斷哪些控制項是可見的，並顯示或隱藏這些控制項。

• Web 資源及 IFRAME 控制項方法
  使用 getData、setData、getInitialUrl、getObject、setSrc 和 getSrc 方法，與 Web 資源及 IFRAME 控制項進行互動。

已停用

使用 getDisabled 和 setDisabled，偵測控制項是否已停用，或加以啟用或停用。

**控制項類型：**標準、查詢、選項組。

getDisabled

傳回控制項是否已停用。

Xrm.Page.getControl(arg).getDisabled()

• 傳回值
  **類型：**布林。 如果控制項已停用則為 true，否則為 false。

setDisabled

設定控制項是否已停用。

Xrm.Page.getControl(arg).setDisabled(bool)

• 引數
  **類型：**布林。 如果必須停用控制項則為 true，否則為 false。

getAttribute

傳回控制項繫結至的屬性。

**控制項類型：**標準、查詢、選項組。

Xrm.Page.getControl(arg).getAttribute()

備註

未繫結至屬性 (子格、Web 資源及 IFRAME) 的控制項沒有此方法。 如果您嘗試在下列其中一個控制項上使用這個方法，就會擲回錯誤。

• 傳回值
  **類型：**物件：屬性。

備註

快速檢視表控制項中的組成控制項會包含在控制項集合中，而且這些控制項具有 getAttribute 方法。 不過，屬性並非實體屬性集合中的一部分。 雖然您可以使用 getValue 擷取該屬性的值，甚至使用 setValue 變更這個值，您所做的變更不會與實體一起儲存。

下列程式碼示範如何在利用名稱為 contactQuickForm 的快速檢視表控制項，將連絡人 mobilephone 屬性顯示於客戶實體表單上時，使用該屬性的值。 這個程式碼會在屬性值為 null 時隱藏控制項。

var quickViewMobilePhoneControl = Xrm.Page.getControl("contactQuickForm_contactQuickForm_contact_mobilephone");
 if (quickViewMobilePhoneControl.getAttribute().getValue() == null)
 {
  quickViewMobilePhoneControl.setVisible(false);
 }

getControlType

傳回會將控制項分類的值。

**控制項類型：**所有。

Xrm.Page.getControl(arg).getControlType()

• 傳回值
  **類型：**字串

  getControlType 可能的傳回值：

  傳回值	描述
  standard	標準控制項。
  iframe	IFRAME 控制項
  lookup	查詢控制項。
  optionset	選項組控制項。
  subgrid	子格控制項。
  webresource	Web 資源控制項。
  notes	附註控制項。
  timercontrol	計時器控制項。
  kbsearch	知識庫搜尋控制項。

getName

傳回指派給控制項的名稱。

備註

在表單載入以前，不會確定指派給控制項的名稱。 對表單的變更可能會變更指派給特定控制項的名稱。

**控制項類型：**所有。

Xrm.Page.getControl(arg).getName()

• 傳回值
  **類型：**字串。 控制項的名稱。

getParent

傳回包含控制項之區段物件的參考。

**控制項類型：**所有。

Xrm.Page.getControl(arg).getParent()

• 傳回值
  類型：Xrm.Page.ui 區段 (用戶端參考) 物件。

知識庫控制項方法

這些方法僅適用於 Microsoft Dynamics CRM Online 組織與 Parature 整合時可用的知識庫搜尋控制項。 這些方法在 Microsoft Dynamics CRM Online 2015 更新 1 引入。

如需這些控制項的詳細資訊，請參閱 Parature 知識庫搜尋控制項 (用戶端參考)。

標籤

使用 getLabel 和 setLabel 方法，取得或變更控制項的標籤。

**控制項類型：**所有。

getLabel

傳回控制項的標籤。

Xrm.Page.getControl(arg).getLabel()

• 傳回值
  **類型：**字串。 控制項的標籤。

setLabel

設定控制項的標籤。

Xrm.Page.getControl(arg).setLabel(label)

• 引數
  **類型：**字串。 控制項的新標籤。

查詢控制項方法及事件

使用 addCustomFilter、addCustomView、getDefaultView 和 setDefaultView 方法，在使用者設定查詢控制項值時，控制向使用者顯示可從中選擇的結果。Lookup 控制項也會公開 PreSearch 事件，以便透過程式設計方式使用 addPreSearch 和 removePreSearch 方法來新增事件處理常式。

**控制項類型：**查詢。

addCustomFilter

用來新增篩選至查詢顯示結果。 每個篩選會使用任何先前新增的篩選做為「AND」條件。

Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)

• 引數

  • filterXml
    **類型：**字串：要套用的 fetchXml 篩選元素。 例如：

    <filter type="and">
     <condition attribute="address1_city" operator="eq" value="Redmond" />
    </filter>
    

  • entityLogicalName
    **類型：**字串：(選擇性) 如果設定此項，篩選只套用至該實體類型。 否則套用至所有傳回的實體類型。

• 備註
  其他資訊：FetchXML schema。

  此方法僅適用於更新的實體。

  此方法只能用於 查詢控制項 PreSearch 事件 事件處理常式中的函數。

  以下是商機表單客戶 (parentaccountid) 查詢的程式碼範例。 在 Onload 事件處理常式中設定 Sdk.setParentAccountIdFilter 函數時，Sdk.filterCustomAccounts 函數會新增至該查詢的 PreSearch 事件。 結果是，只會傳回含有 [偏好的客戶] (1) 之 [類別] (accountcategorycode) 值的客戶。

  var Sdk = window.Sdk || {};
  
  Sdk.filterCustomerAccounts = function () {
      //Only show accounts with the type 'Preferred Customer'
      var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
      Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
  }
  //set 'Sdk.setParentAccountIdFilter' in the Opportunity form onload event handler
  Sdk.setParentAccountIdFilter = function () {
      Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
  }
  

addCustomView

加入查詢對話方塊的新檢視表。

Xrm.Page.getControl(arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)

• 引數

  • viewId
    **類型：**字串：檢視表 GUID 的字串表示。

    備註

    這個值永遠不會儲存，而且只需要是在查詢的其他可用檢視表之中的唯一值。 可以使用非有效 GUID 的字串，例如 "{00000000-0000-0000-0000-000000000001}"。 建議您使用類似 guidgen.exe 的工具產生有效的 GUID。guidgen.exe 工具包含在 Windows SDK 中。

  • entityName
    **類型：**字串：實體的名稱。

  • viewDisplayName
    **類型：**字串：檢視表的名稱。

  • fetchXml
    字串：檢視表的 fetchXml 查詢。

  • layoutXml
    **類型：**字串：定義檢視表配置的 XML。

  • isdefault
    **類型：**布林：檢視表是否必須為預設檢視表。

• 備註
  此方法不適用於 [負責人] 查詢。 負責人查詢是用來指派使用者擁有的記錄。

DefaultView

您可以使用 getDefaultView 和 setDefaultView，偵測哪個檢視表是要顯示來讓使用者選擇查詢中記錄的預設檢視表，以及變更預設檢視表。

getDefaultView

傳回預設查詢對話方塊檢視表的識別碼值。

Xrm.Page.getControl(arg).getDefaultView()

• 傳回值
  **類型：**字串。 預設檢視表的識別碼值。

setDefaultView

設定查詢控制項對話方塊的預設檢視表。

Xrm.Page.getControl(arg).setDefaultView(viewGuid)

• 引數
  **類型：**字串。 要設定為預設檢視表之檢視表的識別碼。

範例：此 setDefaultViewSample 函數可以將 account 實體表單主要連絡人查詢預設檢視表設為 [我的現行連絡人] 檢視表。

function setDefaultViewSample() {
    Xrm.Page.getControl("primarycontactid").setDefaultView("{00000000-0000-0000-00AA-000010001003}");
}​

PreSearch 事件

您可以使用 addPreSearch 和 removePreSearch 方法，新增或移除 查詢控制項 PreSearch 事件 的事件處理常式。

使用 PreSearch 事件，利用使用者開始搜尋記錄時的最新表單資料來控制顯示控制項的哪些結果。

這兩個方法都會將 執行內容 (用戶端參考) 當做第一個參數傳遞。

addPreSearch

使用這個方法，根據使用者即將檢視查詢結果時的最新值，將變更套用至查詢。

Xrm.Page.getControl(arg).addPreSearch(handler)

• 引數
  **類型：**要新增的函數。

• 備註
  此方法僅適用於更新的實體。

引數是一個函數，這個函數正好在搜尋以提供所發生查詢的結果之前執行。 您可以使用這個處理常式，呼叫其中一個其他查詢控制項函數，並改善要在查詢中顯示的結果。

removePreSearch

使用這個方法來移除先前為 PreSearch 事件設定的事件處理常式。

Xrm.Page.getControl(arg).removePreSearch(handler)

• 引數
  **類型：**要移除的函數。

• 備註
  此方法僅適用於更新的實體。

通知

使用 setNotification 顯示關於控制項的通知，並使用 clearNotification 移除該通知。

setNotification

顯示鄰近控制項的訊息，指出該資料為無效。 在 平板電腦專用 Microsoft Dynamics CRM 上使用此方法時，控制項旁邊會出現紅色「X」圖示。 點選圖示將會顯示訊息。

Xrm.Page.getControl(arg).setNotification(message,uniqueId)

備註

在控制項上設定通知將會阻擋表單儲存。

此方法僅適用於更新的實體。

引數

• 訊息
  **類型：**字串：要顯示的訊息。

• uniqueId
  **類型：**字串：只是要在使用 clearNotification 時，用來清除此訊息的識別碼。

傳回值

**類型：**布林：表示方法是否成功。

clearNotification

移除控制項已顯示的訊息。

Xrm.Page.getControl(arg).clearNotification(uniqueId)

引數

• uniqueId
  **類型：**字串：要用來清除使用 setNotification 所設定之特定訊息的識別碼。

  如果沒有使用 uniqueId 參數，將會移除顯示的目前通知。

備註

此方法僅適用於更新的實體。

傳回值

**類型：**布林：表示方法是否成功。

OptionSet 控制項方法

使用 addOption、clearOptions 和 removeOption 方法來操作 OptionSet 控制項可用的選項。 如需使用這些函數的範例，請參閱範例：建立相依 OptionSets (挑選清單)。

addOption

新增選項至選項組控制項。

Xrm.Page.getControl(arg).addOption(option, [index])

重要

此方法不會檢查您在選項中新增的值是否有效。 如果新增無法正確運作的無效選項。 您只應新增針對控制項所繫結之特定選項組屬性定義的選項。 使用 getOptions 屬性或 getOption 方法來取得要使用此方法新增的有效選項物件。

• 引數

  • 選項
    **類型：**物件：要新增至 OptionSet 的選項物件。

  • 索引
    **類型:**數值：(選擇性) 放置新選項的索引位置。 如果沒有提供，選項將會加入至結尾。

clearOptions

清除選項組控制項中的所有選項。

Xrm.Page.getControl(arg).clearOptions()

removeOption

從選項組控制項移除選項。

Xrm.Page.getControl(arg).removeOption(number)

• 引數
  類型：數值：要移除之選項的值。

setFocus

設定焦點在控制項上。

Xrm.Page.getControl(arg).setFocus()

ShowTime

使用 setShowTime 指定日期控制項是否應顯示日期的時間部分，以及在 Microsoft Dynamics CRM Online 2015 更新 1 和更新版本中，使用 getShowTime 判斷日期的時間部分目前是否顯示。

getShowTime

取得日期控制項是否顯示日期的時間部分。

控制項類型：datetime 屬性的標準控制項。

var showsTime = Xrm.Page.getControl(arg).getShowTime();

備註

此方法已在 Microsoft Dynamics CRM Online 2015 更新 1 中引進。

setShowTime

指定日期控制項是否要顯示日期的時間部分。

控制項類型：datetime 屬性的標準控制項。

Xrm.Page.getControl(arg).setShowTime(bool)

備註

此方法僅適用於更新的實體。 屬性使用 DateAndTime 格式時，此方法將顯示或隱藏日期控制項的時間元件。 使用 DateOnly 格式時，此方法沒有任何作用。

子格控制項方法

對於 Microsoft Dynamics CRM Online 2015 更新 1 以前發行的版本，唯一可用於子格控制項的方法是 refresh。 在 CRM Online 2015 更新 1 中，有新功能可使用。其他資訊：Grid 物件和方法 (用戶端參考)

refresh

重新整理子格中顯示的資料。

Xrm.Page.getControl(arg).refresh()

備註

在表單 OnLoad 事件 中無法使用重新整理方法，因為子格會以非同步方式載入。 在 CRM Online 2015 更新 1 引入子格 OnLoad 事件 之後，您現在可以偵測子格載入的時間，以及針對該事件搭配事件處理常式使用此方法。

可見

使用 getVisible 和 setVisible 方法，判斷哪些控制項是可見的，並顯示或隱藏這些控制項。

getVisible

傳回表示控制項目前是否為可見的值。

備註

如果包含此控制項的區段或索引標籤並非可見，此方法仍然可以傳回 true。 若要確定控制項實際可見，您還需要檢查包含元素的顯示性。

Xrm.Page.getControl(arg).getVisible()

• 傳回值
  **類型：**布林。 如果控制項為可見則為 True，否則為 false。

setVisible

設定表示控制項目前是否為可見的值。

Xrm.Page.getControl(arg).setVisible(bool)

• 引數
  **類型：**布林。 如果必須顯示控制項則為 True，否則為 false。

備註

當您使用 Onload 事件執行的程式碼，選擇性地向使用者顯示欄位，建議您將欄位設定為不是預設可見，然後在條件符合時使用 setVisible(true) 顯示此欄位。 在 Onload 事件中使用 setVisible(false) 隱藏欄位，可能導致欄位在隱藏之前短暫顯示給使用者。

如果您要使用 setVisible(false) 隱藏大量欄位，請考慮是否可以將這些欄位群組在索引標籤或區段中，並且隱藏索引標籤或區段而非個別欄位。 這可以改善效能。

Web 資源及 IFRAME 控制項方法

使用這些方法，與 Web 資源及 IFRAME 控制項進行互動。

備註

這些方法不適用於 平板電腦專用 Microsoft Dynamics CRM。

資料

Web 資源具有傳遞自訂資料的特別查詢字串參數，名為 data。getData 和 setData 方法僅適用於新增至表單的 Silverlight Web 資源。其他資訊：從表單傳送資料至內嵌 Silverlight Web 資源

如果是網頁 (HTML) Web 資源，data 參數可以透過 getSrc 方法來擷取，或使用 setSrc 方法來設定。

getData

傳回傳遞至 Silverlight Web 資源的資料查詢字串參數的值。

Xrm.Page.getControl(arg).getData()

• 傳回值
  **類型：**字串。 傳遞至 Silverlight Web 資源的資料值。

setData

設定傳遞至 Silverlight Web 資源的資料查詢字串參數的值。

Xrm.Page.getControl(arg).setData(string)

• 引數
  **類型：**字串。 要傳遞至 Silverlight Web 資源的資料值。

getInitialUrl

傳回 IFRAME 控制項設定要顯示的預設 URL。 此方法不適用於 Web 資源。

Xrm.Page.getControl(arg).getInitialUrl()

• 傳回值
  **類型：**字串。 初始 URL。

getObject

傳回表單中代表 IFRAME 或 Web 資源的物件。

Xrm.Page.getControl(arg).getObject()

• 傳回值
  **類型：**物件。 何種物件取決於控制項類型。

  IFRAME 會從文件物件模型 (DOM) 傳回 IFrame 元素。

  Silverlight Web 資源將會從 DOM 傳回代表內嵌 Silverlight 外掛程式的 Object 元素。

Src

IFRAME 或 Web 資源具有定義內嵌視窗所要顯示之內容的 src 屬性。 您可以使用 getSrc 和 setSrc 方法，取得或變更 src 屬性。

getSrc

傳回 IFRAME 或 Web 資源正在顯示的目前 URL。

Xrm.Page.getControl(arg).getSrc()

• 傳回值
  **類型：**字串。URL，表示 IFRAME 或 Web 資源之 src 屬性。

setSrc

設定要顯示在 IFRAME 或 Web 資源中的 URL。

Xrm.Page.getControl(arg).setSrc(string)

• 引數
  **類型：**字串：URL。

另請參閱

用戶端程式設計參考
表單指令碼快速參考
Xrm.Page.ui (用戶端參考)
撰寫 Microsoft Dynamics CRM 2015 表單的程式碼
使用 Xrm.Page 物件模型

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權