navigateTo (客户端 API 参考)

导航到指定的表列表、表记录、HTML Web 资源或自定义页面。

注释

此方法仅在统一接口上受支持。

语法

使用以下语法调用 Xrm.Navigation.navigateTo()。

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

Parameters

该方法接受以下参数。

Name 类型 必填 说明
pageInput 对象 Yes 有关要导航到的页面的输入。 请参阅 pageInput 参数
navigationOptions 对象 No 导航到页面的选项:是打开内联还是对话框中。 如果未指定此参数,此方法默认将打开页面内联。
successCallback 函数 No 成功内联导航或对话框关闭后要执行的函数。 对于支持返回值的页类型,该函数接收该值作为其参数。
errorCallback 函数 No 作失败时要执行的函数。

pageInput 参数

对象定义根据要导航到的页面类型而更改: 实体列表、 实体记录、 仪表板、 HTML Web 资源、 自定义页面或 生成页。

实体列表

实体列表对象包含以下值。

Name 类型 说明
pageType 字符串 指定 entitylist。
entityName 字符串 要加载到列表控件中的表的逻辑名称。
viewId 字符串 (可选)要加载的视图的 ID。 如果未指定它,应用将导航到表的默认主视图。
viewType 字符串 (可选)要加载的视图类型。 指定 savedquery 或 userquery。

实体记录

实体记录对象包含以下值。

Name 类型 说明
pageType 字符串 指定 entityrecord。
entityName 字符串 要为其显示窗体的表的逻辑名称。
entityId 字符串 (可选)要为其显示窗体的表记录的 ID。 如果未指定此值,窗体将在创建模式下打开。
createFromEntity 查找 (可选)指定基于映射列值提供默认值的记录。 查找对象具有下列字符串属性:entityType、id 和 name(可选)。
data 对象 (可选)将额外参数传递给窗体的字典对象。

这些参数可以是新窗体上设置的默认值的表列(请参阅 使用传递给窗体的参数设置列值),也可以是窗体上访问 formContext.data.attributes 的自定义参数(请参阅 “配置窗体以接受自定义查询字符串参数”和 formContext.data)。 无效的参数会导致错误。

formId 字符串 (可选)要显示的窗体实例的 ID。
isCrossEntityNavigate 布尔 (可选)指示是否使用跨表业务流程从其他表导航到该窗体。
isOfflineSyncError 布尔 (可选)指示是否存在任何脱机同步错误。
processId 字符串 (可选)要显示在窗体上的业务流程的 ID。
processInstanceId 字符串 (可选)要显示在窗体上的业务流程实例的 ID。
relationship 对象 (可选)定义关系对象以在窗体上显示相关记录。 查看 关系。
selectedStageId 字符串 (可选)业务流程实例中所选阶段的 ID。
tabName 字符串 (可选)设置窗体选项卡上的焦点。

了解如何使用客户端 API 在对话框中打开主窗体

关系对象

实体记录中使用的关系对象包含以下值。

Name 类型 说明
attributeName 字符串 用于关系的列的名称。
name 字符串 关系的名称。
navigationPropertyName 字符串 此关系的导航属性的名称。
relationshipType 编号 关系类型。 指定以下值之一: 0:OneToMany、 1:ManyToMany。
roleType 编号 关系中的角色类型。 指定以下值之一: 1:Referencing、 2:AssociationEntity。

Dashboard

若要打开pageInput,请使用此对象作为参数。

仪表板对象包含以下值。

Name 类型 说明
pageType 字符串 指定 dashboard。
dashboardId 字符串 要加载的仪表板的 ID。 如果未指定 ID,应用将导航到默认仪表板。

HTML Web 资源

若要打开 pageInput,请使用此对象作为参数。

HTML Web 资源对象包含以下值。

Name 类型 说明
pageType 字符串 指定 webresource。
webresourceName 字符串 要加载的 Web 资源的名称。
data 字符串 (可选)要传递给 Web 资源的数据。

自定义页面

若要打开pageInput,请使用此对象作为参数。

自定义页面对象包含以下值。

Name 类型 说明
pageType 字符串 指定 custom。
name 字符串 要打开的自定义页的逻辑名称。
entityName 字符串 (可选)要通过 Param("entityName")的自定义页面中提供的表的逻辑名称。
recordId 字符串 (可选)要通过 Param("recordId")的自定义页面中提供的表记录的 ID。

生成页

若要打开pageInput,请使用此对象作为参数。

若要使用 recordId、 entityName或 data目标生成页,必须 设置为接受输入参数。

生成页对象包含以下值。

Name 类型 说明
pageType 字符串 指定 generative。
pageId 字符串 要打开的生成页的 ID。
recordId 字符串 (可选)要传递给页面的记录的 GUID。
entityName 字符串 (可选)与 对应的 recordIdDataverse 表的逻辑名称。
data 对象 (可选)包含要传递给页面的其他自定义参数的 JSON 对象。

请参阅演示如何使用客户端 API 导航到生成页和从生成页导航的示例

该 navigationOptions 对象包含以下值。

Name 类型 说明
target 编号 指定 1 以内联打开页面。 指定 2 在对话框中打开页面。
此外,仅当在此值(对话框中打开页面)中指定 2 时,其余值(宽度、高度和位置)才有效。
注意:只能内联打开实体列表。 可以在内联或对话框中打开实体记录、Web 资源和生成页。
width Number 或 Object (可选)对话框的宽度。 若要指定宽度(以像素为单位),请键入数值。 若要以百分比为单位指定宽度,请使用以下属性指定 SizeValue 类型的对象:
- value:Number 类型的数值。
- unit:String 类型的度量单位。 指定 % 或 px。 默认值为 px。
height Number 或 Object (可选)对话框的高度。 若要指定高度(以像素为单位),请键入数值。 若要以百分比为单位指定宽度,请使用以下属性指定 SizeValue 类型的对象:
- value:Number 类型的数值。
- unit:String 类型的度量单位。 指定 % 或 px。 默认值为 px。
position 编号 (可选)指定 1 以在中心打开对话; 2 在远端打开对话。 默认值为 1 (居中)。
title 字符串 (可选)中心或侧对话顶部的对话框标题。

返回值

返回一个承诺。 当 promise 解析时传递的值取决于目标和页面类型:

  • 内联:承诺在导航完成且不返回值时解析。
  • 对话框:承诺在对话框关闭时解析。
    • 对于在创建模式下打开的实体记录,promise 使用包含 savedEntityReference 数组的对象解析。
    • 对于生成页,promise 使用其 returnValue 属性包含最近传递给 dataApi.setPageOutput(value)的值的对象解析。 如果生成页未设置输出值,则通过选择 “取消” 或关闭按钮关闭对话框会导致未定义 returnValue。
    • 当对话框关闭时,其他页面类型不会返回值。

savedEntityReference为实体记录返回的数组包含以下属性:

  • entityType:表的逻辑名称。
  • id:记录 GUID 的字符串表示形式。
  • name:记录的主列值。

Examples

以下示例演示如何在内联和对话框中导航到不同的页面类型。

Example 演示
打开帐户列表 如何以内联方式打开主帐户列表。
在对话框中打开现有帐户记录 如何在具有指定高度和宽度的居中对话框中打开现有帐户记录。
在对话框中的创建模式下打开帐户窗体 如何在对话框中以创建模式打开帐户窗体,并访问保存的记录的 ID 和名称。
在对话框中打开 HTML Web 资源 如何在对话框中打开 HTML Web 资源,其维度以像素为单位。
在对话框中打开包含输入参数的生成页 如何将记录上下文和自定义参数传递给生成页对话框并读取其返回值。

打开帐户列表示例

以内联的方式打开主帐户列表。

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 Web 资源

在对话框中打开 HTML Web 资源。

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
导航到生成页和从生成页导航
导航到自定义页面和从自定义页面(预览版)