# SAP Analytics Cloud 自定义小组件开发 ## 目录 * 概述 * 插件组件 * 快速启动 * 社区示例小部件 * 关键概念 * 常见错误及解决方案 * 捆绑资源 ## 概述此技能支持为 SAP Analytics Cloud (SAC) 开发自定义小部件。自定义小部件是 Web 组件，可通过自定义可视化、交互元素和专用功能来扩展 SAC 故事和应用程序。 **在以下情况下使用此技能**： * 构建标准 SAC 中不可用的自定义可视化 * 集成第三方图表库（ECharts、D3.js、Chart.js） * 为SAC应用程序创建交互式输入组件 * 实施专门的数据显示或 KPI 小部件 * 使用自定义功能扩展 Analytics Designer 应用程序 * 解决自定义小部件加载或数据绑定问题 **要求**： * 拥有优化故事体验或分析设计师的 SAC 租户 * JavaScript/Web 组件知识 * 外部托管（GitHub Pages、AWS S3、Azure）或 SAC 托管资源（QRC 2023 年第二季度以上） ** ** ## 插件组件该插件提供专门的代理、命令和验证挂钩，以提供全面的小部件开发支持。 ### 代理代理|颜色 |目的|触发示例 ---|---|---|--- **小部件架构师** |蓝色|设计小部件结构、元数据和集成模式 | “设计自定义小部件”、“规划小部件架构” **小部件调试器** |黄色|解决加载、数据绑定、CORS 和运行时问题 | “小部件无法加载”、“CORS 错误”、“数据未绑定” **widget-api-assistant** |绿色|编写 JavaScript 小部件代码、生命周期函数、API 集成 | “编写小部件代码”、“实现生命周期功能” ### 命令命令|用途 |描述 ---|---|--- `/widget-validate` | `/widget-validate [文件]` |验证 widget.json 架构和 widget.js 结构 `/widget-generate` | `/widget-generate` |使用 JSON + JS 交互生成 widget 脚手架 `/widget-lint` | `/widget-lint [文件]` |性能、安全性和最佳实践分析 ### 验证挂钩写入/编辑操作触发自动质量检查： * **widget.json** ：必填字段、标签命名、属性类型、数据绑定配置 * **widget.js** ：生命周期函数、Shadow DOM、propertiesChanged 调度 * **性能** ：调整大小、去抖动、图表处理、XSS 预防 * **上下文提醒**：模板建议、命令建议 ### 模板 `templates/` 目录中现成的脚手架： * `basic-widget.js` \- 具有所有生命周期功能的最小 Web 组件 * `data-bound-chart.js` \- 带数据绑定的 ECharts 小部件 * `styling-panel.js` \- 运行时自定义面板 * `widget.json-minimal` \- 裸最小元数据 * `widget.json-complete` \- 具有所有选项的全功能元数据 ** ** ## 快速入门 ### 最小自定义小部件结构自定义小部件需要两个文件： **1\. widget.json**（元数据） { "id": "com.company.mywidget", “版本”：“1.0.0”， "name": "我的自定义小部件", "description": "一个简单的自定义小部件", "vendor": "公司名称", “许可证”：“麻省理工学院”， “图标”：“”， “网络组件”：[ { “种类”：“主要”， “标签”：“我的自定义小部件”， "url": "[https://your-host.com/widget.js",](https://your-host.com/widget.js",) “诚信”：“”， “忽略完整性”：true } ], “属性”：{ “标题”：{ “类型”：“字符串”， “默认”：“我的小部件” } }, “方法”：{}， “事件”：{} } **2\. widget.js**（Web 组件）（函数（）{ const template = document.createElement("template"); 模板.innerHTML = ` <风格> ：主机{ 显示：块；宽度：100%；高度：100%； } .容器{ 内边距：16px；字体系列：Arial、无衬线字体； }

我的小部件

`; 类 MyCustomWidget 扩展 HTMLElement { 构造函数（）{ 超级（）； this._shadowRoot = this.attachShadow({ 模式: "打开" }); this._shadowRoot.appendChild(template.content.cloneNode(true)); this._props = {}; } 连接回调() { // 当元素添加到 DOM 时调用 } onCustomWidgetBeforeUpdate(changedProperties) { // 在更新属性之前调用 this._props = { ...this._props, ...changedProperties }; } onCustomWidgetAfterUpdate(changedProperties) { // 更新属性后调用 - 在此渲染 if (changedProperties.title !== 未定义) { this._shadowRoot.getElementById("title").textContent =changedProperties.title; } } onCustomWidgetResize() { // 当小部件调整大小时调用 } onCustomWidgetDestroy() { // 删除小部件时进行清理 } // 属性 getter/setter（SAC 框架必需）获取标题() { 返回 this._props.title； } 设置标题（值）{ this._props.title = 值； this.dispatchEvent(new CustomEvent("propertiesChanged", { 详细信息：{ 属性：{ 标题：值 } } })); } } customElements.define("my-custom-widget", MyCustomWidget); })(); **⚠️ 生产说明**：上面的 `ignoreIntegrity: true` 设置仅用于 **开发**。对于生产部署，生成 SHA256 完整性哈希并设置“ignoreIntegrity: false”。 ** ** ## 社区示例小部件 SAP 提供了 15 个以上即用型自定义小部件示例： **存储库**：[SAP-samples/SAC_Custom_Widgets]() 类别 |小部件 ---|--- **图表** |漏斗、帕累托、桑基、旭日、树、线、UI5 甘特图 **KPI/指标** | KPI 环、规格等级、半甜甜圈、嵌套饼、定制饼 **公用事业** |文件上传、文字云、条形渐变、小部件附加示例 **要求**：启用优化视图模式 (OVM)，支持数据绑定 **注意**：在生产使用之前检查第三方库许可证。 ** ** ## 关键概念 ### 生命周期函数 SAC框架调用的基本函数： * `onCustomWidgetBeforeUpdate(changedProperties)` \- 预更新钩子 * `onCustomWidgetAfterUpdate(changedProperties)` \- 更新后（在此处渲染） * `onCustomWidgetResize()` \- 处理调整大小事件 * `onCustomWidgetDestroy()` \- 清理资源 ### 数据绑定在 widget.json 中配置以接收 SAC 模型数据： { “数据绑定”：{ “我的数据绑定”：{ “饲料”：[ { “id”：“尺寸”， “描述”：“尺寸”， “类型”：“维度” }, { "id": "措施", “描述”：“措施”， “类型”：“主要结构成员” } ] } } } 在 JavaScript 中访问数据： // 获取数据绑定 const dataBinding = this.dataBindings.getDataBinding("myDataBinding"); // 访问结果集 const 数据 = this.myDataBinding.data; const 元数据 = this.myDataBinding.metadata; // 迭代行 this.myDataBinding.data.forEach(行 => { 常量维度值 = row.dimensions_0.label; constmeasureValue = row.measures_0.raw; }); ### 托管选项 **1\. SAC 托管（推荐，QRC 2023 年第二季度以上）** * 直接上传文件至SAC > 文件 > 公共文件 * 使用相对路径：`"/path/to/widget.js"` * 设置 `"integrity": ""` 和 `"ignoreIntegrity": true` **2\. GitHub 页面** * 使用小部件文件创建存储库 * 在设置中启用 GitHub Pages * 使用 URL: `[https://username.github.io/repo/widget.js`]([https://username.github.io/repo/widget.js`]()) **3\.外部网络服务器** * AWS S3、Azure Blob 或任何 HTTPS 服务器 * 必须包含 CORS 标头：`Access-Control-Allow-Origin: *` ### 安全性：完整性哈希对于生产环境，生成 SHA256 哈希值： # 生成哈希值 openssl dgst -sha256 -二进制 widget.js | openssl base64 -A # 更新 JSON "完整性": "sha256-abc123...", “忽略完整性”：错误 ** ** ## 常见错误及解决方案错误 |原因 |解决方案 ---|---|--- “系统无法加载自定义小部件” | URL 不正确或托管问题 |验证 URL 是否可访问，检查 CORS “完整性检查失败” |哈希不匹配 | JS改变后重新生成hash 小部件未出现 |缺少connectedCallback渲染|在onCustomWidgetAfterUpdate中调用render 属性未更新 |缺少属性更改调度 |使用带有propertiesChanged的dispatchEvent 数据未显示 |数据绑定配置错误 |验证 JSON 中的 feed 匹配使用情况 ** ** ## 调试 ### 浏览器开发工具 1. 打开 Chrome 开发者工具 (F12) 2. Sources选项卡：找到widget.js，设置断点 3. Console选项卡：查看console.log输出 4.网络选项卡：检查文件是否加载（200状态） ### 调试模式 onCustomWidgetAfterUpdate(changedProperties) { console.log("小部件已更新：",changedProperties); console.log("当前道具：", this._props); console.log("数据绑定：", this.myDataBinding?.data); this._render(); } ** ** ## 小部件附加组件（QRC Q4 2023+）小部件附加组件可扩展内置 SAC 小部件，无需从头开始构建。 **用例**： * 自定义图表工具提示 * 添加视觉元素到绘图区域 * 覆盖内置样式 **支持的图表**：条形图/柱形图、堆积条形图/柱形图、折线图、堆积面积图、数字点 **主要区别**： * 仅“main”和“builder”组件（无“styling”） * 必须指定扩展目标（`tooltip`、`plotArea`、`numericPoint`） * SAC通过方法提供图表上下文数据请参阅 **`references/widget-addon-guide.md`** 了解完整的实现。 ** ** ## 捆绑资源 ### 模板（即用型代码） * **`templates/basic-widget.js`** \- 最小 Web 组件脚手架（约 60 行） * **`templates/data-bound-chart.js`** \- 具有 SAC 数据绑定的 ECharts 小部件（约 120 行） * **`templates/styling-panel.js`** \- 用于运行时自定义的样式面板（约 150 行） * **`templates/widget.json-minimal`** \- 最小元数据（约 25 行） * **`templates/widget.json-complete`** \- 全功能元数据（约 100 行） ### 参考文档 1. **`references/json-schema-reference.md`** \- 完整的 JSON schema 文档 2. **`references/widget-templates.md`** \- 附加小部件模板模式（6个模板） 3. **`references/echarts-integration.md`** \- ECharts库集成指南 4. **`references/widget-addon-guide.md`** \- Widget 插件开发 (QRC Q4 2023+) 5. **`references/best-practices-guide.md`** \- 性能、安全性和开发指南 6. **`references/advanced-topics.md`** \- 自定义类型、脚本API类型、安装 7. **`references/integration-and-migration.md`** \- 脚本集成、内容传输 8. **`references/script-api-reference.md`** \- DataSource、Selection、MemberInfo API ** ** ## 官方文档链接 **主要参考**（用于技能更新）： * [自定义小部件开发人员指南]() * [开发人员指南 PDF]() * [Widget API PDF (2025)]() **示例小部件**： * [SAP 示例存储库]() * [SAP 自定义小部件 GitHub]() ** ** ## 版本历史 **v2.0.0** (2025-12-27) * 添加了 3 个专门代理：widget-architect、widget-debugger、widget-api-assistant * 添加了 3 个斜线命令：/widget-validate、/widget-generate、/widget-lint * 添加了用于写入/编辑自动质量检查的验证挂钩 * 在 templates/ 目录中添加了 5 个可用于生产的模板 * 增强的插件结构以匹配全面的插件模式 * 更新了最后验证日期 **v1.2.0** (2025-11-26) * 将 SAC 版本参考更新为 2025.21 * 优化 SKILL.md 长度，从 563 行减少到约 200 行 * 为所有 8 个参考文件添加了目录 * 改进的渐进式披露架构 **v1.1.0** (2025-11-22) * 添加了小组件附加功能文档 (QRC Q4 2023+) * 添加了最佳实践指南（性能、安全、开发） * 添加了高级主题（自定义类型、脚本 API 类型、安装） * 使用附加关键字增强描述 * 将错误预防覆盖率提高到 25+ **v1.0.0** (2025-11-22) * 初始版本 * 完整的 JSON 元数据参考 * 生命周期函数文档 * 数据绑定指南 * 样式面板的实现 * 托管选项（SAC 托管、GitHub、外部） * 安全性（完整性哈希、CORS） * 常见错误及调试 ** ** **最后验证**：2025 年 12 月 27 日 | **SAC 版本**：2025.21 | **技能版本**：2.0.0

Sap Sac 自定义小部件

包含技能