在 Dynamics 365 自定义按钮中，应避免使用 document.location.href 等原生跳转方式，而需调用 Xrm.Navigation.navigateTo() API，以复现系统内置导航（如网格行点击）的单页应用（SPA）行为，保持导航栏、筛选器、上下文状态等不重载。
在 dynamics 365 自定义按钮中，应避免使用 `document.location.href` 等原生跳转方式，而需调用 `xrm.navigation.navigateto()` api，以复现系统内置导航（如网格行点击）的单页应用（spa）行为，保持导航栏、筛选器、上下文状态等不重载。
Dynamics 365 是基于现代前端框架构建的单页应用（SPA），其内部导航（例如点击网格中的记录链接）并非传统 HTTP 页面跳转，而是通过前端路由机制动态加载模块，从而保留顶部导航栏、左侧导航菜单、当前视图筛选条件、活动记录集（Record Set）以及页面状态（如已展开的选项卡、滚动位置等）。若直接使用 document.location.href = '...'、window.location.replace() 或模拟 <a></a> 标签点击，将触发整页刷新（full page reload），导致所有 SPA 上下文丢失——这正是你观察到“导航栏重载”“记录集选项消失”的根本原因。
✅ 正确做法：使用 Xrm.Navigation.navigateTo()
该 API 是 Microsoft 官方推荐且专为 Dynamics 365 模块化导航设计的接口，支持实体表单、自定义页面、Web 资源等多种目标，并自动继承当前用户上下文与 UI 状态。
基础用法示例：
// 导航至指定实体记录（编辑模式）
function navigateToRecord(entityLogicalName, recordId, openInNewWindow = false) {
const navOptions = {
entityName: entityLogicalName, // 如 'account', 'contact'
entityId: recordId, // GUID 字符串，格式：'{12345678-9ABC-DEF0-1234-567890ABCDEF}'
openInNewWindow: openInNewWindow // true → 新标签页；false → 当前窗口内 SPA 导航
};
return Xrm.Navigation.navigateTo(navOptions)
.then(() => console.log("导航成功"))
.catch(error => console.error("导航失败:", error.message));
}
// 在按钮中调用（建议绑定到事件处理器而非内联 onclick）
document.getElementById("btnNavigateToAccount").addEventListener("click", function () {
navigateToRecord("account", "{a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8}");
});
其他常用导航场景：
-
✅ 打开新记录表单（新建）：
Xrm.Navigation.openForm({ entityName: "account", useQuickCreateForm: false }); -
✅ 导航至自定义页面（Canvas App / Web Resource）：
Xrm.Navigation.navigateTo({ pageType: "webresource", webresourceName: "new_/html/custom-dashboard.html" }); -
✅ 导航至高级查找视图（Advanced Find）：
Xrm.Navigation.navigateTo({ pageType: "entitylist", entityName: "account", viewId: "{00000000-0000-0000-0000-000000000000}" // 可选：指定视图 GUID });
⚠️ 重要注意事项：
-
Xrm.Navigation仅在 Dynamics 365 Web 客户端（即浏览器中）可用，不适用于 Outlook 客户端或移动 App； - 必须确保脚本在
Xrm对象就绪后执行（例如在formContext.getEventSource().addOnLoad()或Xrm.Utility.getGlobalContext()可用之后）； -
recordId必须为标准 GUID 格式（含大括号{}），且需经过 URL 编码（若手动拼接）；但navigateTo()内部会自动处理，无需额外编码； - 避免回退使用
document.createElement('a').click()模拟链接——这仍可能触发页面重载，且无法复现 Dynamics 的路由上下文。
? 总结：要获得与系统 <a></a> 链接完全一致的导航体验，唯一可靠的方式是采用 Xrm.Navigation.navigateTo() 及其配套 API。它不是“替代方案”，而是 Dynamics 365 前端架构的官方契约接口——尊重并使用它，才能真正融入平台生态，保障用户体验一致性与功能稳定性。
