navigateTo (用戶端 API 參考)

導覽至指定的表格清單、表格記錄、HTML Web 資源或自訂頁面。

備註

此方法僅在統一介面上受支援。

句法

請使用以下語法來呼叫 Xrm.Navigation.navigateTo()。

Xrm.Navigation.navigateTo(pageInput,navigationOptions).then(successCallback,errorCallback);

Parameters

此方法接受以下參數。

名稱 類型 必填 描述
頁面輸入 物件 是的 輸入要導覽的頁面。 請參閱 pageInput 參數
navigationOptions 物件 No 導覽至頁面的選項:是內嵌開啟還是在對話方塊中開啟。 如果你沒有指定這個參數,這個方法預設會以內嵌方式開啟頁面。
successCallback 函式 No 一個在成功內嵌導航或對話框結束時執行的功能。 對於支援回傳值的頁面類型,函式會接收該值作為參數。
errorCallback 函數 No 作業失敗時要執行的函式。

pageInput 參數

物件定義會依瀏覽頁面類型而改變: 實體清單、 實體記錄、 儀表板、 HTML 網頁資源、 自訂頁面或 生成頁面。

實體清單

實體清單物件包含下列值。

名稱 類型 描述
pageType 字串 指定 entitylist。
entityName 字串 要載入清單控制項中的資料表的邏輯名稱。
viewId 字串 (選用)要載入的檢視 ID。 如果你沒指定,應用程式會導覽到表格的預設主檢視。
viewType 字串 (選用)要載入的視圖類型。 指定 savedquery 或 userquery。

實體記錄

實體記錄物件包含下列值。

名稱 類型 描述
pageType 字串 指定 entityrecord。
entityName 字串 要顯示表單的資料表的邏輯名稱。
entityId 字串 (選用)要顯示表單的資料表記錄的 ID。 如果你沒指定這個值,表單會以建立模式開啟。
createFromEntity 查詢 (可選)指定一個記錄,根據映射欄位值提供預設值。 查閱物件具有下列 String 屬性:entityType、id 和 name (選擇性)。
data 物件 (選用)將額外參數傳遞至表單的字典物件。

參數可以是具有在新表單上設定的預設值的資料表資料行 (請參閱使用 傳遞至表單的參數設定資料行值) ,或在 formContext.data.attributes 表單上存取的自訂參數 (請參閱 設定表單以接受自訂查詢字串參數,以及 formContext.data)。 參數無效會導致錯誤。

formId 字串 (可選)要顯示的表單實例的 ID。
isCrossEntityNavigate 布林值 (選用)指出是否使用跨資料表商務程序流程從不同的資料表導覽至表單。
isOfflineSyncError 布林值 (選用)指出是否有任何離線同步處理錯誤。
processId 字串 (可選)業務流程的識別碼,顯示在表單上。
processInstanceId 字串 (可選)業務流程實例的 ID,顯示在表單上。
relationship 物件 (選用)定義關係物件,以在表單上顯示相關記錄。 參見 關係。
selectedStageId 字串 (選用)商業程序實例中所選階段的 ID。
tabName 字串 (選用)將焦點設定在表單的索引標籤上。

學習如何利用客戶端 API 在對話框中開啟主表單

關係物件

實體 記錄中使用的關聯性物件包含下列值。

名稱 類型 描述
attributeName 字串 用於關聯性的欄名稱。
name 字串 關係的名稱。
navigationPropertyName 字串 此關聯性的導覽屬性名稱。
relationshipType 數量 關係類型。 指定下列其中一個值: 0:OneToMany、 1:ManyToMany。
roleType 數量 關係中的角色類型。 指定下列其中一個值: 1:Referencing、 2:AssociationEntity。

儀表板

當你想開啟pageInput時,可以用這個物件作為參數。

儀表板物件包含下列值。

名稱 類型 描述
pageType 字串 指定 dashboard。
dashboardId 字串 要載入的儀表板 ID。 如果你沒指定 ID,應用程式會直接導向預設儀表板。

HTML 網頁資源

當你想開啟 pageInput時,可以用這個物件作為參數。

HTML Web 資源物件包含下列值。

名稱 類型 描述
pageType 字串 指定 webresource。
webresourceName 字串 要載入的 Web 資源名稱。
data 字串 (選用)要傳遞至 Web 資源的資料。

自訂頁面

當你想開啟pageInput時,可以用這個物件作為參數。

自訂頁面物件包含以下值。

名稱 類型 描述
pageType 字串 指定 custom。
name 字串 要開啟的自訂頁面的邏輯名稱。
entityName 字串 (選用)要透過 在 Param("entityName")自訂頁面中提供的資料表邏輯名稱。
recordId 字串 (選用)要透過 在 Param("recordId")自訂頁面中提供的表格記錄 ID 。

生成頁面

當你想開啟pageInput時,可以用這個物件作為參數。

要使用 recordId、 entityName、 或 data,必須設定目標生成頁面 以接受輸入參數。

生成頁面物件包含以下值。

名稱 類型 描述
pageType 字串 指定 generative。
pageId 字串 開啟生成頁面的 ID。
recordId 字串 (可選)記錄的 GUID,要傳到頁面。
entityName 字串 (可選)Dataverse 資料表的邏輯名稱,對應於 recordId。
data 物件 (可選)一個包含額外自訂參數的 JSON 物件,可以傳遞給頁面。

請參考範例說明如何利用客戶端 API 導航至生成頁面與離開頁面

該 navigationOptions 物件包含以下值。

名稱 類型 描述
target 數量 請指定 1 以內文開啟頁面。 指定 2 以對話框開啟該頁面。
另外,其他值(寬度、高度和位置)只有在你指定 2 這個值(在對話框中開啟頁面)時才有效。
注意:你只能在線上開啟實體清單。 你可以在內聯或對話框中開啟實體記錄、網路資源和生成頁面。
width 數字或物件 (選用)對話方塊的寬度。 要指定寬度(以像素為單位),請輸入數值。 若要以百分比指定寬度,請指定具有下列屬性的 SizeValue 類型的物件:
- value:類型為「數字」的數值。
- unit:字串類型的測量單位。 指定 % 或 px。 預設值為 px。
height 數字或物件 (選用)對話的高度。 要指定高度(像素),請輸入數值。 若要以百分比指定寬度,請指定具有下列屬性的 SizeValue 類型的物件:
- value:Number 類型的數值。
- unit:字串類型的測量單位。 指定 % 或 px。 預設值為 px。
position 數量 (選用)指定 1 以在中心開啟對話方塊; 2 以在遠端開啟對話方塊。 預設值為 1 (中心)。
title 字串 (選用)中央或側邊對話方塊頂端的對話方塊標題。

返回值

傳回 Promise。 當承諾解決時傳遞的值取決於目標和頁面類型:

  • 內嵌:當導航完成且不回傳值時,承諾會被解析。
  • 對話:當對話結束時,承諾會解決。
    • 對於在建立模式開啟的實體記錄,承諾會以包含 savedEntityReference 陣列的物件來解析。
    • 對於生成頁面,承諾會以一個物件解析,其 returnValue 屬性包含最近傳遞給 dataApi.setPageOutput(value)的值。 如果生成頁面沒有設定輸出值,選擇 取消 或關閉按鈕關閉對話框,會顯示一個未定義 returnValue的 。
    • 其他頁面類型在對話框關閉時不會回傳值。

savedEntityReference實體記錄回傳的陣列包含以下屬性:

  • entityType:資料表的邏輯名稱。
  • id:記錄 GUID 的字串表示。
  • 名稱:記錄的主要欄位值。

Examples

以下範例示範如何在內聯與對話框中切換到不同頁面類型。

範例 演示
開放帳戶清單 如何在線上開啟主帳戶清單。
在對話框中開啟現有帳戶紀錄 如何在居中對話框中開啟現有帳戶紀錄,並設定高度和寬度。
在對話框中的建立模式中開啟帳戶表單 如何在對話框中以建立模式開啟帳戶表單,並存取已儲存紀錄的 ID 和名稱。
在對話框中開啟一個 HTML 網頁資源 如何在以像素為單位的對話框中開啟 HTML 網頁資源。
開啟一個帶有輸入參數的生成頁面 如何將記錄上下文與自訂參數傳遞給生成頁面對話框並讀取其回傳值。

開放帳戶清單範例

直接開啟主帳戶清單。

var pageInput = {
    pageType: "entitylist",
    entityName: "account"
};
Xrm.Navigation.navigateTo(pageInput).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

在對話範例中開啟現有帳戶紀錄

在對話框中開啟一個現有的帳戶表單。

var pageInput = {
    pageType: "entityrecord",
    entityName: "account",
    entityId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" //replace with actual ID
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

學習如何利用客戶端 API 在對話框中開啟主表單

在對話範例中的建立模式開啟帳戶表單

在對話框中以建立模式開啟帳戶表單,儲存後回傳已建立的紀錄參考。

var pageInput = {
    pageType: "entityrecord",
    entityName: "account"    
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success(result) {
            console.log("Record created with ID: " + result.savedEntityReference[0].id + 
            " Name: " + result.savedEntityReference[0].name)
            // Handle dialog closed
    },
    function error() {
            // Handle errors
    }
);

學習如何利用客戶端 API 在對話框中開啟主表單

在對話範例中開啟一個 HTML 網頁資源

在對話框中開啟一個 HTML 網頁資源。

var pageInput = {
    pageType: "webresource",
    webresourceName: "new_sample_webresource.htm"
};
var navigationOptions = {
    target: 2,
    width: 500, // value specified in pixel
    height: 400, // value specified in pixel
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

在對話範例中開啟一個帶有輸入參數的生成頁面

以置中對話框開啟生成頁面,傳遞記錄 ID、實體名稱及自訂資料參數。 生成頁面必須設定 成接受這些參數。

var pageInput = {
    pageType: "generative",
    pageId: "<genPageID>", // replace with the ID of your generative page
    recordId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", // replace with actual record GUID
    entityName: "account",
    data: { status: "active", category: "premium" }
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit: "%"},
    width: {value: 70, unit: "%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success(result) {
        const output = result?.returnValue;
        if (output) {
            console.log("Value returned by generative page:", output);
        }
    },
    function error(error) {
        console.log(error.message);
    }
);

Xrm.Navigation
導覽至生成頁面
導覽至自訂頁面或導覽自訂頁面 (預覽版)