sapui5-linter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAPUI5 Linter Skill

SAPUI5 Linter 技能

Overview

概述

The UI5 Linter (@ui5/linter) is a static code analysis tool designed specifically for SAPUI5 and OpenUI5 projects. It helps developers identify compatibility issues, deprecated APIs, security concerns, and best practice violations before upgrading to UI5 2.x.

Key Capabilities:

✅ Detects 19 categories of issues including deprecated APIs, global usage, and CSP violations
✅ Automatic fixes for common issues (no-globals, no-deprecated-api, manifest properties)
✅ Supports JavaScript, TypeScript, XML, JSON, HTML, and YAML files
✅ Configurable ignore patterns and file targeting
✅ Multiple output formats: stylish, JSON, Markdown, HTML
✅ Fast performance: 1-40s depending on project size

Current Version: 1.20.5 (November 2025) Official Repository: https://github.com/UI5/linter

UI5 Linter (@ui5/linter) 是一款专为SAPUI5和OpenUI5项目设计的静态代码分析工具。它能帮助开发者在升级到UI5 2.x之前识别兼容性问题、废弃API、安全隐患以及最佳实践违规情况。

核心功能:

✅ 检测19类问题，包括废弃API、全局变量使用、CSP违规等
✅ 自动修复常见问题（禁用全局变量、废弃API、manifest属性）
✅ 支持JavaScript、TypeScript、XML、JSON、HTML和YAML文件
✅ 可配置忽略规则和目标文件
✅ 多种输出格式：stylish、JSON、Markdown、HTML
✅ 性能高效：根据项目大小，耗时1-40秒

当前版本: 1.20.5（2025年11月） 官方仓库: https://github.com/UI5/linter

Quick Start

快速开始

Prerequisites

前置条件

Node.js: v20.11.x, v22.0.0, or higher npm: v8.0.0 or higher

Verify prerequisites:

bash

node --version  # Should be v20.11+ or v22+
npm --version   # Should be v8+

Node.js: v20.11.x、v22.0.0或更高版本 npm: v8.0.0或更高版本

验证前置条件：

bash

node --version  # 应显示v20.11+或v22+
npm --version   # 应显示v8+

Installation

安装

Global Installation (recommended for CLI usage):

bash

npm install --global @ui5/linter

Local Installation (recommended for project integration):

bash

npm install --save-dev @ui5/linter

Verify installation:

bash

ui5lint --version  # Should output: 1.20.5 or higher

全局安装（推荐用于CLI使用）：

bash

npm install --global @ui5/linter

本地安装（推荐用于项目集成）：

bash

npm install --save-dev @ui5/linter

验证安装：

bash

ui5lint --version  # 应输出：1.20.5或更高版本

Basic Usage

基础使用

Run linter from project root:

bash

undefined

从项目根目录运行检查工具：

bash

undefined

Lint entire project

检查整个项目

ui5lint

Lint specific files or directories

检查特定文件或目录

ui5lint "webapp/**/*.js" ui5ling "webapp/controller/" "webapp/view/"

Show detailed information about findings

显示检查结果的详细信息

ui5lint --details

undefined

ui5lint --details

undefined

Common Workflows

常见工作流

Development Workflow:

bash

undefined

开发工作流:

bash

undefined

1. Check for issues with details

1. 查看带详细信息的问题

ui5lint --details

2. Preview automatic fixes

2. 预览自动修复效果

UI5LINT_FIX_DRY_RUN=true ui5lint --fix

3. Apply fixes

3. 应用修复

ui5lint --fix

4. Review changes

4. 查看变更

git diff

5. Verify fixes worked

5. 验证修复是否生效

ui5lint --details

undefined

ui5lint --details

undefined

Configuration

配置

Configuration File Setup

配置文件设置

Create

ui5lint.config.{js|mjs|cjs}

javascript

module.exports = {
  rules: {
    // Recommended rules
    "no-deprecated-api": "error",
    "no-globals": "error",
    "no-ambiguous-event-handler": "error",
    "no-outdated-manifest-version": "error"
  },
  exclude: [
    "dist/**",
    "node_modules/**",
    "test/**/*.{spec,js,ts}"
  ]
};

创建

ui5lint.config.{js|mjs|cjs}

：

javascript

module.exports = {
  rules: {
    // 推荐规则
    "no-deprecated-api": "error",
    "no-globals": "error",
    "no-ambiguous-event-handler": "error",
    "no-outdated-manifest-version": "error"
  },
  exclude: [
    "dist/**",
    "node_modules/**",
    "test/**/*.{spec,js,ts}"
  ]
};

Common Configuration Patterns

常见配置模式

javascript

// Strict for production, relaxed for development
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  rules: {
    "no-deprecated-api": isProduction ? "error" : "warn",
    "no-globals": isProduction ? "error" : "warn"
  },
  exclude: [
    "legacy/**/*",
    "**/*.min.js"
  ]
};

javascript

// 生产环境严格模式，开发环境宽松模式
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  rules: {
    "no-deprecated-api": isProduction ? "error" : "warn",
    "no-globals": isProduction ? "error" : "warn"
  },
  exclude: [
    "legacy/**/*",
    "**/*.min.js"
  ]
};

CLI Usage

CLI 使用

Essential Commands

核心命令

bash

undefined

bash

undefined

Basic linting

基础检查

ui5lint

With detailed output

带详细输出

ui5lint --details

Fix auto-fixable issues

自动修复可修复问题

ui5lint --fix

JSON output for CI/CD

输出JSON格式用于CI/CD

ui5lint --format json

HTML report for documentation

生成HTML报告用于文档

ui5lint --format html --details

Performance monitoring

性能监控

ui5lint --perf

undefined

ui5lint --perf

undefined

Linting Rules Overview

检查规则概述

Async & Modern Patterns

异步与现代模式

async-component-flags: Validates async component configuration
prefer-test-starter: Validates Test Starter implementation

async-component-flags: 验证异步组件配置
prefer-test-starter: 验证Test Starter实现

Security

安全

csp-unsafe-inline-script: Detects unsafe inline scripts

csp-unsafe-inline-script: 检测不安全的内联脚本

Event Handlers

事件处理程序

no-ambiguous-event-handler: Ensures proper event handler notation ✅ Autofix

no-ambiguous-event-handler: 确保事件处理程序符号正确 ✅ 支持自动修复

Deprecation Detection (7 Rules)

废弃检测（7条规则）

no-deprecated-api: Detects deprecated APIs ✅
no-deprecated-component: Finds deprecated component dependencies
no-deprecated-control-renderer: Validates control renderer patterns
no-deprecated-library: Checks deprecated libraries in manifest

no-deprecated-api: 检测废弃API ✅
no-deprecated-component: 查找废弃组件依赖
no-deprecated-control-renderer: 验证控件渲染器模式
no-deprecated-library: 检查manifest中的废弃库

Global Usage

全局变量使用

no-globals: Identifies global variable usage ✅ Autofix
no-implicit-globals: Detects implicit global access

no-globals: 识别全局变量使用 ✅ 支持自动修复
no-implicit-globals: 检测隐式全局访问

Error Reporting

错误报告

parsing-error: Reports syntax/parsing errors
autofix-error: Reports autofix failures

parsing-error: 报告语法/解析错误
autofix-error: 报告自动修复失败

API Usage

API 使用

ui5-class-declaration: Verifies UI5 class declaration patterns (TypeScript)
unsupported-api-usage: Ensures proper API usage

ui5-class-declaration: 验证UI5类声明模式（TypeScript）
unsupported-api-usage: 确保API正确使用

Manifest Modernization (3 Rules)

Manifest 现代化（3条规则）

no-outdated-manifest-version: Requires Manifest Version 2
no-removed-manifest-property: Identifies incompatible properties ✅ Autofix

no-outdated-manifest-version: 要求使用Manifest Version 2
no-removed-manifest-property: 识别不兼容属性 ✅ 支持自动修复

Complete rules reference**: See

references/rules-complete.md

完整规则参考**: 查看

references/rules-complete.md

Integration with Development Workflows

与开发工作流集成

package.json Scripts

package.json 脚本

json

{
  "scripts": {
    "lint": "ui5lint",
    "lint:fix": "ui5lint --fix",
    "lint:details": "ui5lint --details",
    "lint:ci": "ui5lint --quiet --format json > lint-results.json",
    "lint:report": "ui5lint --format html --details > lint-report.html"
  },
  "devDependencies": {
    "@ui5/linter": "^1.20.5"
  }
}

json

{
  "scripts": {
    "lint": "ui5lint",
    "lint:fix": "ui5lint --fix",
    "lint:details": "ui5lint --details",
    "lint:ci": "ui5lint --quiet --format json > lint-results.json",
    "lint:report": "ui5lint --format html --details > lint-report.html"
  },
  "devDependencies": {
    "@ui5/linter": "^1.20.5"
  }
}

Common Scenarios

常见场景

Scenario 1: New UI5 Project Setup

场景1：新建UI5项目设置

Install linter
Create configuration (use template)
Add npm scripts to package.json
Run initial lint
Fix auto-fixable issues
Review remaining issues

安装检查工具
创建配置文件（使用模板）
在package.json中添加npm脚本
运行初始检查
修复可自动修复的问题
审查剩余问题

Scenario 2: Preparing for UI5 2.x Migration

场景2：准备UI5 2.x迁移

Run linter to find all issues
Focus on critical issues first
Apply automatic fixes
Review autofix limitations document
Manually fix unsupported APIs
Address Core API issues (#619, #620)
Update manifest to v2
Fix no-outdated-manifest-version, no-removed-manifest-property issues
Verify all issues resolved

运行检查工具找出所有问题
优先处理关键问题
应用自动修复
查看自动修复限制文档
手动修复不支持自动修复的API
解决核心API问题（#619、#620）
将manifest更新到v2版本
修复no-outdated-manifest-version、no-removed-manifest-property问题
验证所有问题已解决

Troubleshooting

故障排除

Common Issues

常见问题

Symptom: Linter reports parsing errors Solution: Check for syntax errors in config files

Symptom: Autofix doesn't work Solution: Check autofix limitations in

references/autofix-complete.md

Symptom: Performance issues on large codebase Solution: Add ignore patterns, use targeted linting

症状: 检查工具报告解析错误 解决方案: 检查配置文件中的语法错误

症状: 自动修复不生效 解决方案: 查看

references/autofix-complete.md

中的自动修复限制

症状: 大型代码库上性能不佳 解决方案: 添加忽略规则，使用针对性检查

Known Limitations

已知限制

Cannot convert synchronous to async patterns
Limited Core/Configuration API autofix (~50 APIs)
jQuery.sap API support limited to basic methods
Node.js modules not automatically discovered

无法将同步模式转换为异步模式
核心/配置API自动修复支持有限（约50个API）
jQuery.sap API仅支持基础方法
Node.js模块无法自动识别

Best Practices

最佳实践

1. Run Linter Early and Often

1. 尽早并频繁运行检查工具

Add pre-commit hook for instant feedback
See templates/husky-pre-commit.template

添加预提交钩子以获取即时反馈
查看 templates/husky-pre-commit.template

2. Use Configuration File for Persistent Settings

2. 使用配置文件保存持久设置

Environment-specific configurations
Project-wide ignore patterns

环境特定配置
项目级忽略规则

3. Fix Issues Incrementally

3. 逐步修复问题

Fix errors first
Then fix warnings
Review and test after each step

先修复错误
再修复警告
每一步修复后进行审查和测试

4. Document Suppressed Rules

4. 记录禁用的规则

Document team-wide suppressions with explanations
Use sparingly and with clear justifications

记录团队级禁用规则并说明原因
谨慎使用并提供明确理由

5. Integrate with CI/CD

5. 与CI/CD集成

Fail builds on errors, allow warnings
Generate reports for stakeholders

错误导致构建失败，警告允许通过
为利益相关者生成报告

6. Monitor Performance

6. 监控性能

Track linting performance over time

跟踪检查工具的性能变化

Reference Documentation

参考文档

External Resources

外部资源

Official Repository: https://github.com/UI5/linter
Issue Reporting: https://github.com/UI5/linter/issues
Discussions: https://github.com/UI5/linter/discussions
Chat Support: https://discord.gg/sapui5
SAP Community: https://community.sap.com/tags/ui5

官方仓库: https://github.com/UI5/linter
问题反馈: https://github.com/UI5/linter/issues
讨论区: https://github.com/UI5/linter/discussions
聊天支持: https://discord.gg/sapui5
SAP社区: https://community.sap.com/tags/ui5

Detailed Documentation

详细文档

Complete Rules Reference:
```
references/rules-complete.md
```
Autofix Capabilities:
```
references/autofix-complete.md
```
Performance Guide:
```
references/performance.md
```
Troubleshooting Guide:
```
references/support-and-community.md
```
Contributing Guide:
```
references/contributing.md
```

完整规则参考:
```
references/rules-complete.md
```
自动修复功能:
```
references/autofix-complete.md
```
性能指南:
```
references/performance.md
```
故障排除指南:
```
references/support-and-community.md
```
贡献指南:
```
references/contributing.md
```

Templates

模板

Configuration Template:
```
templates/ui5lint.config.mjs
```
package.json Template:
```
templates/package.json.template
```
Husky Pre-commit:
```
templates/husky-pre-commit.template
```

配置模板:
```
templates/ui5lint.config.mjs
```
package.json模板:
```
templates/package.json.template
```
Husky预提交钩子:
```
templates/husky-pre-commit.template
```

Support and Updates

支持与更新

Version: 1.20.5 (Current)
Release Notes: Available in GitHub releases
Roadmap: Documented in GitHub Issues and Discussions
Email: security@sap.com
Community: Discord #sapui5 channel

版本: 1.20.5（当前）
发布说明: 可在GitHub发布页查看
路线图: 在GitHub Issues和Discussions中记录
邮箱: security@sap.com
社区: Discord #sapui5频道

Bundled Resources

捆绑资源

Reference Documentation

参考文档

```
references/rules-complete.md
```
- Complete reference for all 19 linting rules
```
references/autofix-complete.md
```
- Detailed autofix capabilities and limitations
```
references/performance.md
```
- Performance optimization guide
```
references/support-and-community.md
```
- Support channels and community resources
```
references/contributing.md
```
- Contributing guidelines

```
references/rules-complete.md
```
- 所有19条检查规则的完整参考
```
references/autofix-complete.md
```
- 详细的自动修复功能和限制
```
references/performance.md
```
- 性能优化指南
```
references/support-and-community.md
```
- 支持渠道和社区资源
```
references/contributing.md
```
- 贡献指南

Templates

模板

```
templates/ui5lint.config.mjs
```
- Configuration template
```
templates/package.json.template
```
- Package.json template
```
templates/husky-pre-commit.template
```
- Pre-commit hook template

Last Updated: 2025-11-26 | Version: 1.0.1 (Restructured) Previous Version: 1.0.0 | Lines Reduced: 376 (from 827) Next Review: 2026-02-25

```
templates/ui5lint.config.mjs
```
- 配置模板
```
templates/package.json.template
```
- Package.json模板
```
templates/husky-pre-commit.template
```
- 预提交钩子模板

最后更新: 2025-11-26 | 版本: 1.0.1（重构后） 上一版本: 1.0.0 | 行数减少: 376（从827行） 下次审核: 2026-02-25

sapui5-linter

Original

Translation

SAPUI5 Linter Skill

SAPUI5 Linter 技能

Table of Contents

目录

Overview

概述

Quick Start

快速开始

Prerequisites

前置条件

Installation

安装

Basic Usage

基础使用

Lint entire project

检查整个项目

Lint specific files or directories

检查特定文件或目录

Show detailed information about findings

显示检查结果的详细信息

Common Workflows

常见工作流

1. Check for issues with details

1. 查看带详细信息的问题

2. Preview automatic fixes

2. 预览自动修复效果

3. Apply fixes

3. 应用修复

4. Review changes

4. 查看变更

5. Verify fixes worked

5. 验证修复是否生效

Configuration

配置

Configuration File Setup

配置文件设置

Common Configuration Patterns

常见配置模式

CLI Usage

CLI 使用

Essential Commands

核心命令

Basic linting

基础检查

With detailed output

带详细输出

Fix auto-fixable issues

自动修复可修复问题

JSON output for CI/CD

输出JSON格式用于CI/CD

HTML report for documentation

生成HTML报告用于文档

Performance monitoring

性能监控

Linting Rules Overview

检查规则概述

Async & Modern Patterns

异步与现代模式

Security

安全

Event Handlers

事件处理程序

Deprecation Detection (7 Rules)

废弃检测（7条规则）

Global Usage

全局变量使用

Error Reporting

错误报告

API Usage

API 使用

Manifest Modernization (3 Rules)

Manifest 现代化（3条规则）

Complete rules reference**: See references/rules-complete.md

完整规则参考**: 查看 references/rules-complete.md

Integration with Development Workflows

与开发工作流集成

package.json Scripts

Complete rules reference**: See
`references/rules-complete.md`

完整规则参考**: 查看
`references/rules-complete.md`