navigateTo （客户端 API 参考）

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

注释

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

Syntax

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

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

参数

该方法接受以下参数。

Name	类型	必选	Description
pageInput	物体	是的	有关要导航到的页面的输入。请参阅 pageInput 参数
navigationOptions	物体	否	导航到页面的选项：是打开内联还是对话框中。如果未指定此参数，此方法默认将打开页面内联。
`successCallback`	函数	否	一个函数，用于在导航到内联时成功导航到页面，并在导航到对话框时关闭对话框。
`errorCallback`	功能	否	作失败时要执行的函数。

`pageInput` 参数

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

实体列表

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

Name	类型	Description
`pageType`	String	指定 `entitylist`。
`entityName`	String	要加载到列表控件中的表的逻辑名称。
`viewId`	String	（可选）要加载的视图的 ID。如果未指定它，应用将导航到表的默认主视图。
`viewType`	String	（可选）要加载的视图类型。指定 `savedquery` 或 `userquery`。

实体记录

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

Name	类型	Description
`pageType`	String	指定 `entityrecord`。
`entityName`	String	要为其显示窗体的表的逻辑名称。
`entityId`	String	（可选）要为其显示窗体的表记录的 ID。如果未指定此值，窗体将在创建模式下打开。
`createFromEntity`	查找	（可选）指定基于映射列值提供默认值的记录。查找对象具有以下 String 属性：entityType、id 和 name（可选）。
`data`	物体	（可选）将额外参数传递给窗体的字典对象。这些参数可以是新窗体上设置的默认值的表列（请参阅使用传递给窗体的参数设置列值），也可以是窗体上访问 `formContext.data.attributes` 的自定义参数（请参阅 “配置窗体以接受自定义查询字符串参数”和 formContext.data）。无效的参数会导致错误。
`formId`	String	（可选）要显示的窗体实例的 ID。
`isCrossEntityNavigate`	布尔	（可选）指示是否使用跨表业务流程从其他表导航到该窗体。
`isOfflineSyncError`	布尔	（可选）指示是否存在任何脱机同步错误。
`processId`	String	（可选）要显示在窗体上的业务流程的 ID。
`processInstanceId`	String	（可选）要显示在窗体上的业务流程实例的 ID。
`relationship`	物体	（可选）定义关系对象以在窗体上显示相关记录。查看关系。
`selectedStageId`	String	（可选）业务流程实例中所选阶段的 ID。
`tabName`	String	（可选）设置窗体选项卡上的焦点。

关系对象

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

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

Dashboard

若要打开仪表板，pageInput请使用此对象作为参数。

仪表板对象包含以下值。

Name	类型	Description
`pageType`	String	指定 `dashboard`。
`dashboardId`	String	要加载的仪表板的 ID。如果未指定 ID，应用将导航到默认仪表板。

HTML Web 资源

若要打开 HTML Web 资源，pageInput请使用此对象作为参数。

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

Name	类型	Description
`pageType`	String	指定 `webresource`。
`webresourceName`	String	要加载的 Web 资源的名称。
`data`	String	（可选）要传递给 Web 资源的数据。

自定义页面

若要打开自定义页面，pageInput请使用此对象作为参数。

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

Name	类型	Description
`pageType`	String	指定 `custom`。
`name`	String	要打开的自定义页的逻辑名称。
`entityName`	String	（可选）要通过 `Param("entityName")`的自定义页面中提供的表的逻辑名称。
`recordId`	String	（可选）要通过 `Param("recordId")`的自定义页面中提供的表记录的 ID。

生成页

若要打开生成页，pageInput请使用此对象作为参数。

生成页对象包含以下值。

Name	类型	Description
`pageType`	String	指定 `generative`。
`pageId`	String	要打开的生成页的 ID。

注释

使用 navigateTo 当前导航到生成页 不支持传递初始化或上下文数据 （例如表名称、记录 ID 或自定义参数）。生成页在没有上下文的情况下打开。

`navigationOptions` 参数

该 navigationOptions 对象包含以下值。

Name	类型	Description
`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`	String	（可选）中心或侧对话顶部的对话框标题。

返回值

返回一个承诺。当 promise 解析时传递的值取决于目标：

内联：Promise 立即解析，不返回任何值。
dialog：Promise 在对话框关闭时解析。仅当 pageType = entityRecord 创建模式下打开窗体时，才会传递对象。该对象具有具有以下 savedEntityReference 属性的数组，用于标识创建的表记录：
- entityType：表的逻辑名称。
- id：记录的 GUID 值的字符串表示形式。
- 名称：显示或创建的记录的主列值。

Example

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

示例 1：打开帐户列表

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

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

示例 2：在对话框中打开现有帐户记录

在对话框中打开现有帐户窗体。

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
    }
);

示例 3：在对话框中的创建模式下打开帐户窗体

在对话框中以创建模式打开帐户窗体，并在保存时返回创建的记录引用。

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
    }
);

示例 4：在对话框中打开 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
    }
);

Xrm.Navigation
导航到自定义页面和从自定义页面（预览版）

反馈

此页面是否有帮助？

Last updated on 2026-01-22