sapui5

SAPUI5 开发技能

相关技能

• sap-fiori-tools：用于快速开发 Fiori 应用、配置页面编辑器和自动化部署
• sap-cap-capire：用于后端服务集成、OData 模型绑定和 CAP 服务调用
• sap-btp-cloud-platform：用于部署选项、HTML5 Application Repository 服务和 BTP 集成
• sap-abap：用于连接 ABAP 后端或使用 SAP 系统提供的 OData 服务
• sap-api-style：用于编写 UI5 应用 API 文档或遵循 REST/OData 标准
• sap-dependency-security：用于安全升级依赖、管理锁文件策略、供应链管控，以及在 SAPUI5 前端工具链中固定 MCP 服务的确切版本

何时使用此技能

在构建 SAPUI5/OpenUI5 应用、XML 视图、控制器、自定义控件、路由、OData v2/v4 模型绑定、Fiori Elements 集成、QUnit/OPA5 测试，进行无障碍、安全性和性能改进，或使用 UI5 MCP 辅助搭建项目及查询 API 时，请使用此技能。

这是一个全面的技能，可用于使用 SAP UI5 框架构建企业级应用。

使用 MCP 工具（v2.0.0 新增）

此技能集成了官方 @ui5/mcp-server，提供实时开发工具：

• 项目搭建：使用 ui5-app-scaffolder Agent 或 /ui5-scaffold 命令创建项目
• API 参考：使用 ui5-api-explorer Agent 或 /ui5-api 命令查询控件
• 代码质量：使用 ui5-code-quality-advisor Agent 或 /ui5-lint 命令运行代码检查器
• 迁移：使用 ui5-migration-specialist Agent 升级版本
• 版本信息：使用 /ui5-version 命令查看发布版本
• 工具目录：使用 /ui5-mcp-tools 命令列出所有 MCP 工具

有关设置和故障排除，请参阅 references/mcp-integration.md。MCP 软件包版本固定由 sap-dependency-security 管理，并通过 npm run validate:mcp-security 验证。

平稳回退：无需 MCP 也可使用参考文件和内置模板来实现所有功能。

目录

1. 快速入门
2. 核心概念
3. SAP Fiori Elements
4. 元数据驱动控件（MDC）
5. 测试
6. 最佳实践
7. 常见模式
8. 故障排除
9. 开发工具
10. 打包资源

---

快速入门

创建基本 SAPUI5 应用

使用 UI5 Tooling（推荐）或 SAP Business Application Studio：

# Install UI5 CLI
npm install -g @ui5/cli

# Create new project
mkdir my-sapui5-app && cd my-sapui5-app
npm init -y

# Initialize UI5 project
ui5 init

# Add UI5 dependencies
npm install --save-dev @ui5/cli

# Start development server
ui5 serve

项目结构：

my-sapui5-app/
├── webapp/
│   ├── Component.js
│   ├── manifest.json
│   ├── index.html
│   ├── controller/
│   │   └── Main.controller.js
│   ├── view/
│   │   └── Main.view.xml
│   ├── model/
│   │   └── formatter.js
│   ├── i18n/
│   │   └── i18n.properties
│   ├── css/
│   │   └── style.css
│   └── test/
│       ├── unit/
│       └── integration/
├── ui5.yaml
└── package.json

可用模板：

• templates/basic-component.js：组件模板
• templates/manifest.json：应用描述符模板
• templates/xml-view.xml：包含常见模式的 XML 视图
• templates/controller.js：遵循最佳实践的控制器
• templates/formatter.js：常用格式化函数

使用模板：将模板复制到项目中，并替换占位符（{{namespace}}、{{ControllerName}} 等）。

---

核心概念

1. MVC 架构

• 模型：数据层（JSON、OData、XML、资源模型）
• 视图：表示层（XML、JavaScript、JSON、HTML）
• 控制器：业务逻辑层
• 绑定：同步模型和视图（单向、双向、单次）

参考：references/core-architecture.md，了解详细的架构概念。

2. 组件与清单

• Component.js：入口点，初始化路由器和模型
• manifest.json：集中式配置（模型、路由、依赖项、数据源）

manifest 的主要部分：

• sap.app：应用元数据和数据源
• sap.ui：UI 技术和设备类型
• sap.ui5：UI5 专属配置（模型、路由、依赖项）

3. 数据模型

JSON 模型（客户端）：

var oModel = new JSONModel({
    products: [...]
});
this.getView().setModel(oModel);

OData V2 模型（服务端）：

"": {
    "dataSource": "mainService",
    "settings": {
        "defaultBindingMode": "TwoWay",
        "useBatch": true
    }
}

资源模型（i18n）：

"i18n": {
    "type": "sap.ui.model.resource.ResourceModel",
    "settings": {
        "bundleName": "my.app.i18n.i18n"
    }
}

参考：references/data-binding-models.md，了解全面指南。

4. 视图和控制器

XML 视图（推荐）：

<mvc:View
    controllerName="my.app.controller.Main"
    xmlns="sap.m"
    xmlns:mvc="sap.ui.core.mvc">
    <Page title="{i18n>title}">
        <List items="{/products}">
            <StandardListItem title="{name}" description="{price}"/>
        </List>
    </Page>
</mvc:View>

5. 路由和导航

以编程方式导航：

this.getOwnerComponent().getRouter().navTo("detail", {
    objectId: sId
});

参考：references/routing-navigation.md，了解路由模式。

---

SAP Fiori Elements

使用 OData 注释构建应用，无需编写 JavaScript UI 代码。

应用类型

1. 列表报表：可搜索、可筛选的表格/图表
2. 对象页面：包含区段和方面的详细视图
3. 分析列表页面：视觉筛选器和分析
4. 概览页面：基于卡片的仪表板
5. 工作清单：用于任务的简化列表

快速设置

用于列表报表 + 对象页面的 manifest.json：

{
    "sap.ui5": {
        "dependencies": {
            "libs": {
                "sap.fe.templates": {}
            }
        },
        "routing": {
            "targets": {
                "ProductsList": {
                    "type": "Component",
                    "name": "sap.fe.templates.ListReport",
                    "options": {
                        "settings": {
                            "contextPath": "/Products",
                            "variantManagement": "Page"
                        }
                    }
                }
            }
        }
    }
}

关键注释：

• @UI.LineItem：表格列
• @UI.SelectionFields：筛选栏字段
• @UI.HeaderInfo：对象页面标题
• @UI.Facets：对象页面区段

参考：references/fiori-elements.md，了解全面指南。

---

元数据驱动控件（MDC）

sap.ui.mdc 库提供元数据驱动控件，用于在运行时构建动态 UI。

关键控件

• MDC 表格：根据元数据动态生成列以显示数据
• MDC 筛选栏：使用 PropertyInfo 设置复杂筛选条件
• MDC 值帮助：通过建议辅助输入数据

快速示例

<mdc:Table
    id="mdcTable"
    delegate='{name: "my/app/delegate/TableDelegate", payload: {}}'
    p13nMode="Sort,Filter,Column"
    type="ResponsiveTable">
    <mdc:columns>
        <mdcTable:Column propertyKey="name" header="Name">
            <Text text="{name}"/>
        </mdcTable:Column>
    </mdc:columns>
</mdc:Table>

参考：references/mdc-typescript-advanced.md，了解全面的 MDC 指南和 TypeScript 内容。

---

测试

单元测试（QUnit）

测试单个函数和模块：

QUnit.module("Formatter Tests");
QUnit.test("Should format price correctly", function(assert) {
    var fPrice = 123.456;
    var sResult = formatter.formatPrice(fPrice);
    assert.strictEqual(sResult, "123.46 EUR", "Price formatted");
});

集成测试（OPA5）

测试用户交互和流程：

opaTest("Should navigate to detail page", function(Given, When, Then) {
    Given.iStartMyApp();
    When.onTheWorklistPage.iPressOnTheFirstListItem();
    Then.onTheObjectPage.iShouldSeeTheObjectPage();
    Then.iTeardownMyApp();
});

Mock Server

模拟 OData 后端：

var oMockServer = new MockServer({
    rootUri: "/sap/opu/odata/sap/SERVICE_SRV/"
});
oMockServer.simulate("localService/metadata.xml", {
    sMockdataBaseUrl: "localService/mockdata"
});
oMockServer.start();

参考：references/testing.md，了解全面的测试指南。

---

最佳实践

1. 始终使用异步 - sap.ui.define，在清单中设置 async:true
2. 使用 XML 视图 - 声明式且便于使用工具
3. 正确使用命名空间 - com.mycompany.myapp.controller.Main
4. 国际化 - 文本始终使用 i18n
5. 优先使用数据绑定，而非手动更新 - 自动防护 XSS
6. 安全性 - 启用 CSP、验证输入、使用 HTTPS
7. 性能 - 组件预加载、延迟加载、批量请求
8. 无障碍性 - 语义化控件、标签、键盘导航

---

常见模式

CRUD 操作

// Create
oModel.create("/Products", oData, {success: function() {MessageToast.show("Created");}});

// Read
oModel.read("/Products", {filters: [new Filter("Price", FilterOperator.GT, 100)]});

// Update
oModel.update("/Products(1)", {Price: 200}, {success: function() {MessageToast.show("Updated");}});

// Delete
oModel.remove("/Products(1)", {success: function() {MessageToast.show("Deleted");}});

筛选和排序

var oBinding = this.byId("table").getBinding("items");
oBinding.filter([new Filter("price", FilterOperator.GT, 100)]);
oBinding.sort([new Sorter("name", false)]);

对话框处理

if (!this.pDialog) {
    this.pDialog = this.loadFragment({
        name: "my.app.view.fragments.MyDialog"
    });
}
this.pDialog.then(function(oDialog) {oDialog.open();});

---

常见问题排查

绑定不起作用

1. 检查视图/组件上是否设置了模型
2. 确认绑定路径正确
3. 确认数据已加载
4. 调试：console.log(this.getView().getModel().getData())

OData 调用失败

1. 检查 manifest.json 中的服务 URL
2. 检查 CORS 配置
3. 测试身份验证
4. 使用浏览器的 Network 标签页

视图未显示

1. 检查 manifest.json 中的视图注册
2. 确认路由配置
3. 确认控制器名称匹配
4. 检查浏览器控制台中的错误

性能问题

1. 启用组件预加载
2. 对大型数据集使用增长列表
3. 实现 OData 分页
4. 尽可能使用单向绑定

---

开发工具

UI5 Tooling

ui5 serve    # Development server
ui5 build    # Build for production
npm test     # Run tests

UI5 Inspector

• 用于调试的浏览器扩展
• 查看控件树和绑定
• 性能分析

Support Assistant

• 按 Ctrl+Alt+Shift+S
• 内置质量检查器

---

捆绑的参考文件

此技能包含全面的参考文档（15 个文件）：

1. references/glossary.md：完整的 SAPUI5 术语和概念（100 多个术语）
2. references/core-architecture.md：框架架构、组件、MVC、引导
3. references/data-binding-models.md：数据绑定、模型、筛选器、排序器
4. references/testing.md：QUnit、OPA5、模拟服务、测试自动化
5. references/fiori-elements.md：Fiori Elements 模板、注解、配置
6. references/typescript-support.md：TypeScript 设置、配置、迁移
7. references/routing-navigation.md：路由、导航、灵活列布局
8. references/performance-optimization.md：性能最佳实践、优化
9. references/accessibility.md：WCAG 2.1 合规性、屏幕阅读器、ARIA
10. references/security.md：XSS 防护、CSP、身份验证、CSRF
11. references/mdc-typescript-advanced.md：MDC 控件、TypeScript 控件库
12. references/mcp-integration.md：MCP 设置、故障排除和回退行为
13. references/code-quality-checklist.md：UI5 项目审查清单
14. references/migration-patterns.md：升级和现代化模式
15. references/scaffolding-templates.md：项目脚手架指南

访问这些文件，获取特定主题的详细信息，同时保持主技能内容简洁。

---

包含的模板

templates/ 目录中提供了可直接使用的模板：

1. basic-component.js：包含最佳实践的 Component.js 模板
2. manifest.json：完整的应用描述符模板
3. xml-view.xml：包含常见模式的 XML 视图
4. controller.js：包含生命周期钩子的控制器模板
5. formatter.js：常用格式化函数

---

给 Claude 的说明

使用此技能时：

1. 始终使用异步模式 - sap.ui.define，async:true
2. 优先使用 XML 视图 - 声明性更强，也更便于工具处理
3. 使用数据绑定 - 自动防护 XSS
4. 参考文档文件 - 获取详细信息
5. 使用模板 - 从 templates/ 复制并替换占位符
6. 遵循最佳实践 - 安全性、性能、无障碍性
7. 提供可运行的示例 - 提出建议前先测试代码模式

---

捆绑资源

参考文档

• references/accessibility.md - 无障碍最佳实践
• references/core-architecture.md - 框架架构和组件模式
• references/data-binding-models.md - 数据绑定和模型用法
• references/fiori-elements.md - Fiori Elements 模板和注解
• references/mdc-typescript-advanced.md - MDC 和 TypeScript 指南
• references/mcp-integration.md - MCP 设置和故障排除
• references/migration-patterns.md - 从旧版本迁移
• references/performance-optimization.md - 性能优化技术
• references/testing.md - 测试策略和框架
• references/security.md - XSS、CSP、身份验证和 CSRF 指南

模板

• templates/basic-component.js - 组件开发模板
• templates/controller.js - 控制器模板
• templates/xml-view.xml - XML 视图模板
• templates/formatter.js - 格式化辅助模板
• templates/manifest.json - 应用清单模板

---

许可证：GPL-3.0 下次审查：2026-02-27（每季度）