Qlik Sense Extension 中必须在 paint 方法中用 createElement 或 template 动态注入 HTML，禁止字符串赋值；Qlik API 调用需封装后绑定事件；CSS 应预编译进 style.css 并在 extdef.json 声明；HTML 文件须置于根目录并由 "template" 字段指定路径。
Qlik Sense Extension 中如何正确加载外部 HTML 片段
Qlik Sense 的 widget（更准确叫 Extension）本身不支持直接写 HTML 字符串到 DOM，必须通过 paint 或 resize 生命周期方法动态注入。常见错误是把 HTML 当成字符串直接 innerHTML = '<div>...</div>' 赋值，结果样式丢失、事件不触发、甚至被 Qlik 安全策略拦截。
- 所有 HTML 必须在
paint方法中构建并挂载，且推荐用document.createElement或template标签解析，避免 XSS 风险 - 若 HTML 含内联样式或
<style>，需手动插入<head>或使用shadowRoot（仅限 Qlik Sense Feb 2024+ 的新 Extension SDK） - Qlik 会自动清理上一次
paint的 DOM 节点，所以不要缓存document.getElementById结果，每次重绘都应重新查或重建
如何让 HTML 中的 JavaScript 与 Qlik Engine API 通信
嵌入的 HTML 微件常需读取当前选中字段、触发筛选或获取数据。但直接在 HTML 字符串里写 app.field('Region').selectValues(...) 会报 app is not defined —— 因为 Qlik 的 app 实例只在 Extension 的 definition 和生命周期函数作用域内可用。
- 必须把 Qlik API 调用封装进函数，再通过
element.addEventListener绑定到 HTML 元素上，例如：button.addEventListener('click', () => props.backendApi.getApp().field('Year').selectValues([2023])) - 不要在 HTML 字符串里硬编码
props.backendApi，它在旧版 SDK（v3.x）中叫this.backendApi，新版（v4.0+）才统一为props.backendApi - 若需响应数据变化，别依赖
setInterval轮询，改用props.backendApi.model.on('datachanged', handler)
为什么 CSS 在 HTML 微件里不生效？
Qlik Sense 默认对 Extension 的 DOM 使用 Shadow DOM（v4.0+）或 scoped class（v3.x），导致你在 HTML 里写的 <style>.card { color: red; }</style> 完全不起作用。这不是浏览器问题，是 Qlik 的隔离机制。
- 最稳做法：把 CSS 提前编译进 Extension 的
style.css文件，并确保在extdef.json中声明"css": ["style.css"] - 若必须运行时注入，用
const style = document.createElement('style'); style.textContent = '...'; document.head.appendChild(style);，但注意多次加载会重复插入 - 避免用
!important强覆盖，Qlik 内部组件的样式权重极高，优先调整选择器特异性（如加[data-qlik-extension]）
本地开发时 HTML 加载失败的典型原因
在 Qlik Sense Desktop 或 QSEoW 上调试时，常遇到 HTML 片段空白、控制台报 Failed to load resource: net::ERR_FILE_NOT_FOUND，这基本不是代码问题，而是路径或打包规则没配对。
立即学习“前端免费学习笔记（深入）”；
- Extension 的 HTML 文件（如
widget.html）不能放在assets/下——Qlik 只认根目录下的.html文件，且必须在extdef.json的"template"字段中显式声明路径，例如"template": "widget.html" - 如果用 Webpack 打包，禁止把 HTML 当作模块
import html from './widget.html'，Qlik 不执行 JS 模块的 HTML 解析逻辑 - Qlik 不支持
fetch('./data.json')这类相对路径请求，所有外部资源需走 Qlik 的backendApi.model.global.openDoc()或代理到 Qlik Proxy
Shadow DOM、作用域隔离、路径硬编码、API 实例生命周期——这些不是配置项，是嵌入 HTML 微件时每一步都会撞上的墙。绕开它们的方式不是找“万能模板”，而是每次动手前先确认你用的是哪个 SDK 版本、HTML 是静态模板还是动态生成、以及 CSS 是否真的进了正确的样式上下文。
