导航到指定的表列表、表记录、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 |
对象 | (可选)将额外参数传递给窗体的字典对象。
这些参数可以是新窗体上设置的默认值的表列(请参阅 使用传递给窗体的参数设置列值),也可以是窗体上访问 |
formId |
字符串 | (可选)要显示的窗体实例的 ID。 |
isCrossEntityNavigate |
布尔 | (可选)指示是否使用跨表业务流程从其他表导航到该窗体。 |
isOfflineSyncError |
布尔 | (可选)指示是否存在任何脱机同步错误。 |
processId |
字符串 | (可选)要显示在窗体上的业务流程的 ID。 |
processInstanceId |
字符串 | (可选)要显示在窗体上的业务流程实例的 ID。 |
relationship |
对象 | (可选)定义关系对象以在窗体上显示相关记录。 查看 关系。 |
selectedStageId |
字符串 | (可选)业务流程实例中所选阶段的 ID。 |
tabName |
字符串 | (可选)设置窗体选项卡上的焦点。 |
关系对象
实体记录中使用的关系对象包含以下值。
| Name | 类型 | 说明 |
|---|---|---|
attributeName |
字符串 | 用于关系的列的名称。 |
name |
字符串 | 关系的名称。 |
navigationPropertyName |
字符串 | 此关系的导航属性的名称。 |
relationshipType |
编号 | 关系类型。 指定以下值之一: 0:OneToMany、 1:ManyToMany。 |
roleType |
编号 | 关系中的角色类型。 指定以下值之一: 1:Referencing、 2:AssociationEntity。 |
Dashboard
仪表板对象包含以下值。
| Name | 类型 | 说明 |
|---|---|---|
pageType |
字符串 | 指定 dashboard。 |
dashboardId |
字符串 | 要加载的仪表板的 ID。 如果未指定 ID,应用将导航到默认仪表板。 |
HTML Web 资源
HTML Web 资源对象包含以下值。
| Name | 类型 | 说明 |
|---|---|---|
pageType |
字符串 | 指定 webresource。 |
webresourceName |
字符串 | 要加载的 Web 资源的名称。 |
data |
字符串 | (可选)要传递给 Web 资源的数据。 |
自定义页面
自定义页面对象包含以下值。
| Name | 类型 | 说明 |
|---|---|---|
pageType |
字符串 | 指定 custom。 |
name |
字符串 | 要打开的自定义页的逻辑名称。 |
entityName |
字符串 | (可选)要通过 Param("entityName")的自定义页面中提供的表的逻辑名称。 |
recordId |
字符串 | (可选)要通过 Param("recordId")的自定义页面中提供的表记录的 ID。 |
生成页
若要使用 recordId、 entityName或 data目标生成页,必须 设置为接受输入参数。
生成页对象包含以下值。
| Name | 类型 | 说明 |
|---|---|---|
pageType |
字符串 | 指定 generative。 |
pageId |
字符串 | 要打开的生成页的 ID。 |
recordId |
字符串 | (可选)要传递给页面的记录的 GUID。 |
entityName |
字符串 | (可选)与 对应的 recordIdDataverse 表的逻辑名称。 |
data |
对象 | (可选)包含要传递给页面的其他自定义参数的 JSON 对象。 |
请参阅演示如何使用客户端 API 导航到生成页和从生成页导航的示例
navigationOptions 参数
该 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。 - 当对话框关闭时,其他页面类型不会返回值。
- 对于在创建模式下打开的实体记录,promise 使用包含
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
}
);
在对话框示例中的创建模式下打开帐户窗体
在对话框中以创建模式打开帐户窗体,并在保存时返回创建的记录引用。
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
}
);
在对话框示例中打开 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);
}
);