使用客户端 API 创建侧窗格

开发人员可以使用表示侧窗格集合的 Xrm.App.sidePanes API 在模型驱动应用中创建和管理应用侧窗格。调用 createPane 方法会添加新窗格，该窗格允许导航到任何模型驱动的应用窗体或自定义页面。侧窗格中显示的页面宽度不得小于 300 像素，并根据窗格宽度调整为更大的宽度。

选项卡在侧窗格中分为两组列出：不可关闭和可关闭。在每个组中，选项卡按创建顺序列出。顶部组包含用户无法关闭的窗格，底部组具有用户可关闭的窗格。打开应用时会填充不可关闭组，而可关闭组则根据应用中的用户操作添加。

可以将平台提供的标头与标题和“关闭”按钮一起使用，也可以使用自定义标头。

可以将徽章添加到侧边窗格，以向用户指示更改需要注意。徽章支持三种模式：简单的点、计数或图像。默认情况下，当用户切换到窗格时，徽章会清空。您可以控制徽章何时清空。

应用端窗格仅在 Web 浏览器中受支持，在原生播放器中不可用。

Note

此 API 不适用于 Dynamics 365 Customer Engagement 本地部署。详细信息：Customer Engagement（本地部署）中不支持客户端 API

Examples

在侧窗格中显示生成式页面

使用窗格的 navigate 方法，并配合 pageType: "generative" 和生成页 ID：

const pane = await Xrm.App.sidePanes.createPane({
    title: "My Generative Page",
    paneId: "GenPage",
    canClose: true,
    width: 400
});

await pane.navigate({
    pageType: "generative",
    pageId: "<genPageID>"
});

有关传递记录上下文和自定义参数的信息，请参阅导航到生成式页面以及从该页面返回。

在侧窗格中显示默认视图

本节中的示例演示如何在应用端窗格中显示表的默认视图。预订列表和产品列表以不可关闭的窗格形式打开。

Xrm.App.sidePanes.createPane({
    title: "Reservations",
    imageSrc: "WebResources/sample_reservation_icon",
    paneId: "ReservationList",
    canClose: false
}).then((pane) => {
    pane.navigate({
        pageType: "entitylist",
        entityName: "sample_reservation",
    })
});

显示“预留”表的屏幕截图，其中包含活动预留的列表，包括名称、设备和预留开始日期。

Xrm.App.sidePanes.createPane({
    title: "Products",
    imageSrc: "WebResources/sample_product_icon",
    paneId: "ProductList",
    canClose: false
}).then((pane) => {
    pane.navigate({
        pageType: "entitylist",
        entityName: "sample_product",
    })
});

显示“产品”表的屏幕截图，其中包含可以预留的产品列表。

显示表格行

此示例演示如何在侧窗格中显示行。预订行将在隐藏默认标题且宽度设置为 600 像素的侧窗格中打开。

Xrm.App.sidePanes.createPane({
    title: "Reservation: Ammar Peterson",
    imageSrc: "WebResources/sample_reservation_icon",
    hideHeader: true,
    canClose: true,
    width: 600
}).then((pane) => {
    pane.navigate({
        pageType: "entityrecord",
        entityName: "sample_reservation",
        entityId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    })
});

显示打开单个记录的活动预留列表的屏幕截图。

显示 Web 资源

此示例演示如何在侧窗格中显示 Web 资源。自定义 HTML 页面将在一个侧窗格中打开，其中默认标题可见，关闭按钮处于隐藏状态。

Xrm.App.sidePanes.createPane({
                        title: "Registration Page",
                        imageSrc: "WebResources/msfp_SurveyIcon_32",
                        paneId: "RegistrationPage",
                        canClose: false
                    }).then((pane) => {
                        //navigate to webresource
                        pane.navigate({
                            pageType: "webresource",
                            webresourceName: "new_RegistrationPage",
                        })
                    });

管理侧窗格

除了创建侧窗格以及显示侧窗格中的行或视图外，还可以：

state使用此方法以编程方式折叠侧窗格：

Xrm.App.sidePanes.state = 0;
使用 state 方法以编程方式展开侧窗格：

Xrm.App.sidePanes.state = 1;
通过获取所选窗格来更改属性：

var lastPane = Xrm.App.sidePanes.getSelectedPane();
lastPane.width = 400;
使用 paneId 参数检索特定窗格：

var reservationPane = Xrm.App.sidePanes.getPane("ReservationList");
reservationPane.close();
在窗格中启用徽章属性：

Xrm.App.sidePanes.getSelectedPane().badge = 1;

与 Xrm.App.panels.loadPanel 配合使用

Xrm.Panels.loadPanel API 正被 Xrm.App.sidePanes.createPane 取代，因为前者仅支持单个窗格，而后者支持多个窗格。若要实现从 loadPanel 到 createPane 的过渡，这两个 API 可以一起使用，但有一些限制。如果仅在模型驱动应用中使用 loadPanel，体验将保持不变。但是，如果使用这两个loadPanel和createPane，第一个限制是会为loadPanel显示一个占位符图标。第二个限制是：当用户从 loadPanel 切换到 createPane 时，应用程序会卸载 loadPanel 内容以节省内存，并在切换回来时不保留状态地重新加载该内容。此选项卡切换行为与在多会话应用模式下使用的行为相同，用于管理应用使用的内存。大多数页面类型都正确还原。但是，打开外部网站或 Web 资源时，状态不会还原。

通过切换到使用 createPane，可以通过提供图标和启用 alwaysRender来避免这两个限制。 alwaysRender 在用户切换时会保留窗格内容，但会占用更多内存，因此请谨慎使用。

sidePanes （客户端 API 参考）
loadPanel （客户端 API 参考）
演练：编写您的第一个客户端脚本

反馈

此页面是否有帮助？

上次更新时间为 2026-10-19