Back to Details

sapui5-linter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SAPUI5 Linter Skill

SAPUI5 Linter 技能

Table of Contents

目录

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
ui5lint

Lint specific files or directories

检查特定文件或目录

ui5lint "webapp/**/*.js" ui5ling "webapp/controller/" "webapp/view/"
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
ui5lint --details

2. Preview automatic fixes

2. 预览自动修复效果

UI5LINT_FIX_DRY_RUN=true ui5lint --fix
UI5LINT_FIX_DRY_RUN=true ui5lint --fix

3. Apply fixes

3. 应用修复

ui5lint --fix
ui5lint --fix

4. Review changes

4. 查看变更

git diff
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
ui5lint

With detailed output

带详细输出

ui5lint --details
ui5lint --details

Fix auto-fixable issues

自动修复可修复问题

ui5lint --fix
ui5lint --fix

JSON output for CI/CD

输出JSON格式用于CI/CD

ui5lint --format json
ui5lint --format json

HTML report for documentation

生成HTML报告用于文档

ui5lint --format html --details
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项目设置

  1. Install linter
  2. Create configuration (use template)
  3. Add npm scripts to package.json
  4. Run initial lint
  5. Fix auto-fixable issues
  6. Review remaining issues
  1. 安装检查工具
  2. 创建配置文件（使用模板）
  3. 在package.json中添加npm脚本
  4. 运行初始检查
  5. 修复可自动修复的问题
  6. 审查剩余问题

Scenario 2: Preparing for UI5 2.x Migration

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

  1. Run linter to find all issues
  2. Focus on critical issues first
  3. Apply automatic fixes
  4. Review autofix limitations document
  5. Manually fix unsupported APIs
  6. Address Core API issues (#619, #620)
  7. Update manifest to v2
  8. Fix no-outdated-manifest-version, no-removed-manifest-property issues
  9. Verify all issues resolved
  1. 运行检查工具找出所有问题
  2. 优先处理关键问题
  3. 应用自动修复
  4. 查看自动修复限制文档
  5. 手动修复不支持自动修复的API
  6. 解决核心API问题（#619、#620）
  7. 将manifest更新到v2版本
  8. 修复no-outdated-manifest-version、no-removed-manifest-property问题
  9. 验证所有问题已解决

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. 逐步修复问题

  1. Fix errors first
  2. Then fix warnings
  3. Review and test after each step
  1. 先修复错误
  2. 再修复警告
  3. 每一步修复后进行审查和测试

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

外部资源

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