navigateTo （客户端 API 参考）

2025-10-04

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

注释

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

Syntax

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

仪表板对象包含以下值。

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

HTML Web 资源

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

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

自定义页面

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

Name	类型	Description
`pageType`	String	指定 `custom`。
`name`	String	要打开的自定义页的逻辑名称。
`entityName`	String	（可选）要通过 `Param("entityName")`的自定义页面中提供的表的逻辑名称。
`recordId`	String	（可选）要通过 `Param("recordId")`的自定义页面中提供的表记录的 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 资源

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
导航到自定义页面和从自定义页面（预览版）

反馈

此页面是否有帮助？