在 SAP Analytics Cloud 中开发自定义…

当需要为 SAC 故事或 Analytics Designer 扩展自定义可视化、数据绑定图表、KPI 卡片或 Widget Add-On 时，按此流程生成、验证并上传自定义部件。

适用场景

解决思路

1. 先判定部件角色与数据源模式：图表/表格/KPI/菜单/侧边栏/筛选器/混合控件，并区分 SAC 绑定型与纯 UI 控件型；仅对 SAC 绑定型收集维度、度量/关键指标、日期、版本、筛选器和 feed 顺序，纯 UI 控件改为收集交互、导航、状态、方法/事件、可访问性和响应式布局需求。
2. 接受用户提供的截图、PDF、图片、品牌指南和脱敏数据作为证据，但在生成代码前必须确认技术 ID、feed 映射、资产权利和许可证。
3. 生成前先给出 2-3 个符合角色定位的方案，再生成所选完整包；保持代码与 SAC 兼容，使用数据绑定时保留绑定顺序，导入前先验证并修复。
4. 在受限本地环境中使用 templates/local-builder/ 作为免安装脚手架构建器：纯静态 HTML/CSS/原生 JavaScript，避免公共 CDN 和外部包，导出两个独立下载产物 widget.json 和仅含根级组件 JS 文件的 Resource-ZIP；当 file:// 被阻止时使用 Node 的 server.mjs 回退。
5. 生成图表、KPI、层级、输入工具、Widget Add-On 或基于构建的部件前，先查阅 references/sap-sample-widget-lessons.md，仅用于结构和风险检查，不要复制 SAP 示例代码或资产。
6. 生成后使用 templates/design-runtime/ 作为免构建、文件优先的浏览器预览脚手架，在 SAP 之外模拟部件要点，调整属性/设计令牌/示例数据/视口，比较多个部件并导出 agent 迭代载荷。
7. 将样式限制在 Web Component/Shadow DOM 边界内，不要依赖 SAC 优化故事主题 CSS、SAP shell 选择器或全局故事 CSS 来样式化部件内部；生成包前确认托管模式，因为 SAC ZIP 上传包仅支持组件 JavaScript 和 PNG/JPG 图标。
8. 生成 widget.json 前先决定交付模式：SAC Resource-ZIP 上传与外部 HTTPS 托管使用不同 URL 规则；SAC Resource-ZIP 上传时先单独交付并上传 widget.json，再上传仅含根级组件 JS 文件（如 widget.js、builder.js、styling.js）的 Resource-ZIP，不要包含 widget.json、子文件夹、测试、README、CSS 或 HTML。
9. Resource-ZIP 清单使用根相对组件 URL（如 "/widget.js"）；外部托管使用完整 HTTPS URL；本地预览路径（如 "widget.js"）仅保留在预览配置中，除非目标 SAC 流程明确支持该解析模式。
10. 将简单可配置颜色建模为带十六进制默认值（如 "#f4f7fa"）的 string 属性；仅在确切 SAC 租户和目标面板流程接受后才使用 Color 类型。
11. 对带 builder/styling 面板的部件，在文本编辑期间保留焦点和折叠状态，保持组件 JS 自包含，并验证最终 outputs/ 产物而非仅源码预览。
12. 部件完成后，最终聊天响应必须同时提供两个可下载上传产物：widget.json 清单和 Resource-ZIP。
13. 当部件通过本地测试但被 SAC 拒绝时，查阅 references/production-widget-lessons.md，处理 bundle 中的原始控制字符、Analytics Designer 方法体限制、必需完整性状态、客户端清单验证、图标和字体隔离、用户和语言边界、书签风险、不透明错误二分定位、行为预检守卫和浏览器预览限制；区分租户观察、SAP 文档行为和未确认假设。
14. 将 SAC 属性视为外部状态流：SAC 可能逐个交付属性、回显部件写入的值并改变其表示；合并更新、通过单一读取路径规范化并从合并状态渲染；不要假设属性顺序，也不要在空首次渲染时消费 builder 初始化标志。
15. 清单方法体是 Analytics Designer 脚本：可读写已声明属性，但不能调用私有组件方法。
16. Builder 和 styling 面板是有状态编辑器：保持文本编辑有针对性，使焦点、光标、选择、搜索和折叠状态存活；两个编辑器共享文档时保留未知配置键；一个用户操作对应一次属性派发和一次撤销步骤。
17. 结构化导入或导出时保留稳定 ID、深拷贝嵌套模板、对用户自定义名称使用 null 原型映射，并测试每个语言槽位。
18. 验证构建后的组件文件和最终 Resource-ZIP，而非仅源码辅助文件或浏览器预览；先生成所有输出，再验证，最后写入；独立测试最终 bundle，验证精确 SRI 字节，扫描原始控制字符，并使用真实浏览器验证布局、焦点、字体、指针和生命周期行为。
19. 使用 Node.js 生成 SHA256 完整性值：node -e "const fs=require('node:fs');const crypto=require('node:crypto');const file=process.argv[1]||'widget.js';console.log('sha256-'+crypto.createHash('sha256').update(fs.readFileSync(file)).digest('base64'));" widget.js；macOS/Linux 或 Git Bash 也可用 openssl dgst -sha256 -binary widget.js | openssl base64 -A，并在清单中加 sha256- 前缀。
20. 生产环境将 ignoreIntegrity 设为 false 并填入真实 integrity；开发环境可用 "" 加 ignoreIntegrity: true。
21. 使用 Chrome DevTools 调试：Sources 中给 widget.js 设断点，Console 查看 console.log，Network 检查文件是否 200 加载。
22. 在 onCustomWidgetAfterUpdate 中打印 changedProperties、当前 props 和数据绑定数据后调用 _render()。
23. Widget Add-On 仅使用 main 和 builder 组件（无 styling），必须指定扩展目标（tooltip、plotArea、numericPoint），SAC 通过方法提供图表上下文数据；支持 Bar/Column、Stacked Bar/Column、Line、Stacked Area、Numeric Point。
24. 使用 /widget-validate 验证 widget.json schema 和 widget.js 结构，/widget-generate 交互式生成脚手架，/widget-lint 做性能、安全和最佳实践分析。
25. 修复常见错误：URL/CORS 问题、哈希不匹配、缺少 connectedCallback 渲染、缺少 propertiesChanged 派发、feed 配置错误、控制字符导致 CUSTOM_WIDGET_SERVICE_EXCEPTION、方法体调用组件内部、缺少 integrity 字段、图标未打包、字体被面板 CSS 覆盖、用户/语言值需通过故事脚本属性传入、Color 类型被拒、Resource-ZIP 含多余文件、builder 输入失焦、预览依赖共享辅助脚本、重复菜单项 ID 冲突、面板值未被运行时读取、有效零被默认值覆盖、重命名/复制遗留状态、DOM 测试通过但 SAC 布局失败、大小写不一致的用户名匹配。

适用边界 · 注意事项

• 没有 SAC 租户（需 Optimized Story Experience 或 Analytics Designer）时无法进行真实导入和运行时验证。
• 不具备 JavaScript/Web Components 知识时难以正确实现生命周期、数据绑定和 Shadow DOM。
• 没有外部 HTTPS 托管（GitHub Pages、AWS S3、Azure）或 SAC 托管资源（QRC Q2 2023+）时无法部署部件。