---
url: /v6.2/embed-faq.md
---
# 嵌入集成

如果你正在把 HENGSHI SENSE 集成到自己的门户、业务系统或 OEM 页面里，最常见的问题通常不是“能不能嵌入”，而是“嵌入后怎么和宿主系统协同工作”。这页把最常被客户和客服反复确认的问题集中整理出来。

## 嵌入链接应该从哪里开始拼？

建议始终先从产品页面里生成可用的分享/嵌入链接，再在这个基础上追加参数，而不是完全手写 URL。

* 已经完成登录打通时，通常从发布页或应用页的嵌入链接开始
* 需要在 URL 中指定认证方式时，再追加 `activeAuth`、`reloadUser`、`jwtParam` 等参数
* 需要控制页面表现时，再追加 `header=false`、`pager=false`、`locale=en-US` 这类参数

这样做更稳妥，因为路径层级、资源 hash 和可用参数会随着嵌入对象不同而变化。

相关文档：

* [嵌入样式定制化](embed/iframe.md)
* [外部控制嵌入 URL](embed/url.md)
* [嵌入页面的外部控制](embed/events.md)

## 嵌入 URL 常用参数有哪些？

最常见的是下面几类：

|需求|常用参数|说明|
|-|-|-|
|指定语言|`locale=en-US`|适合多语言门户、OEM 场景|
|隐藏页面标题|`header=false`|常用于发布页嵌入|
|隐藏翻页器|`pager=false`|适合只保留内容区|
|同时隐藏标题和翻页器|`copyright=false`|等价于 `header=false&pager=false`|
|减少边距|`chartPadding=0` 或 `padding=0`|适合紧凑卡片式布局|
|公开链接传参|`appParam=[...]`|用于公开链接下的参数控制|

如果你需要的是“嵌入后还能继续在系统内多层导航”，则要同时考虑嵌入层级参数，例如 `L0 / L1 / L2 / L3` 这类路径级控制。

## 宿主页面可以控制刷新、全屏或联动吗？

可以，但建议优先复用已有页面集成能力，而不是自己在宿主页面里重新实现一套交互。

* **刷新**：优先使用 [嵌入页面的外部控制](embed/events.md) 中已有的外部触发方式
* **全屏**：优先由宿主页面控制 iframe 容器进入全屏，再配合嵌入页布局参数
* **语言切换**：优先由宿主系统切换语言后，统一改写嵌入 URL 上的 `locale`

如果你发现“CLI 或外部脚本改了资源，但嵌入页没同步刷新”，通常更应该先排查宿主页面是否触发了刷新、当前页面是否走缓存，而不是先怀疑嵌入本身失效。

## 嵌入场景下为什么会遇到跨域问题？

最常见的原因是宿主系统域名和 HENGSHI SENSE 域名不同，而浏览器对 iframe、cookie、脚本访问都有同源限制。

通常按下面顺序处理：

1. 优先通过反向代理把宿主系统和 HENGSHI SENSE 放到同一主域或可控代理链路下
2. 必要时在系统配置里设置 `ACCESS_CONTROL_ALLOW_ORIGIN`
3. 如果还涉及宿主页面 JS 直接访问 iframe 内部对象，要先确认这件事是否本来就会被浏览器同源策略拦住

如果只是“页面能打开，但某些 JS 联动失败”，大概率不是 HENGSHI 页面没加载，而是浏览器不允许跨域脚本互访。

## 嵌入场景下，应该优先用 iframe 还是 API？

绝大多数项目，优先推荐 **页面嵌入**。

因为 iframe / 页面集成可以直接复用现成的图表、权限、筛选、发布和样式能力，实施成本更低，也更容易和产品升级保持一致。只有当你明确需要自己重建展示层、交互层或外部系统编排逻辑时，才建议继续往 API 集成方向走。

可以先看：

* [嵌入式数据分析场景解决方案](embed/index.md)
* [应用分享嵌入](publish-analyst-share-embed.md)