SAP OpenUI5 开发规范与最佳实践指南

SAP OpenUI5 开发规范与最佳实践指南

openui5 OpenUI5 lets you build enterprise-ready web applications, responsive to all devices, running on almost any browser of your choice. 项目地址: https://gitcode.com/gh_mirrors/op/openui5

概述

SAP OpenUI5 是一套用于构建企业级 Web 应用程序的前端框架。为了确保代码质量和一致性，OpenUI5 项目制定了一套详细的开发规范。本文将深入解析这些规范，帮助开发者编写更专业、更易维护的 UI5 代码。

通用编码规范

基础规则

1. 开发者友好性：始终考虑使用你代码的其他开发者，避免产生意外情况，提供符合预期的行为
2. 缩进与换行：
   • 使用制表符(Tab)而非空格进行缩进
   • 使用 Unix 风格的换行符(LF)
3. 文件编码：
   • 文本文件使用 UTF-8 编码
   • 属性文件(*.properties)使用 ISO8859-1 编码
4. 注释规范：
   • 不要简单重复代码内容
   • 解释代码中未体现的设计意图
   • 优先使用行注释(//)

JavaScript 编码指南

模块化与作用域

1. 避免全局变量：使用 AMD 模块进行封装
   • 通过 sap.ui.define 定义模块
   • 使用其他库的全局变量时，需明确声明
2. 封装性：不要访问其他对象的私有成员
3. 调试输出：避免使用 console.log()

代码格式化

1. 基本格式：
   • 每个语句后加分号
   • 运算符前后加空格
   • 使用 === 和 !== 而非 == 和 !=
2. 大括号风格：开括号与语句同行
3. 示例格式：

function example(sParam) {
    if (sParam === "test") {
        for (var i = 0; i < 10; i++) {
            // 执行操作
        }
    }
    return true;
}

命名约定

1. 匈牙利命名法（推荐但不强制）：

   • sId：字符串
   • oDomRef：对象
   • $DomRef：jQuery 对象
   • iCount：整数
   • aItems：数组
   • bEnabled：布尔值
   • fnCallback：函数

2. 类命名：使用大驼峰式(ClassName)

3. 保留前缀：

   • sap-ui- 开头的 HTML ID
   • data-sap-ui- 开头的 DOM 属性

类设计规范

类成员设计

1. 私有成员：以下划线开头，如 this._bInitialized
2. 实例方法：定义在原型上

   MyClass.prototype.doSomething = function() {...}
   

3. 静态成员：直接定义在构造函数上

   MyClass.staticMethod = function() {...}
   

方法命名

1. 布尔方法：以 is 或 has 开头

   isOpen() { return true; }
   hasItems() { return this.aItems.length > 0; }
   

2. 事件处理：以 _on 开头

   _onButtonPress() {...}
   

3. Promise方法：使用过去式动词短语

   dataLoaded() { return new Promise(...); }
   

继承与构造

1. 类继承：

   SubClass = SuperClass.extend("namespace.SubClass", {...});
   

2. 构造函数调用：

   function SubClass() {
       SuperClass.apply(this, arguments);
   }
   

UI5 控件开发指南

API 设计原则

1. 命名规范：
   • 控件名：大驼峰式(MyControl)
   • 属性/方法名：小驼峰式(myProperty)
2. 默认值：为属性提供合理的默认值
3. 一致性：参考相似控件的 API 设计
4. XML视图兼容：确保属性类型适合 XML 使用

行为规范

1. ID生成：内部控件 ID 使用 this.getId() + "-suffix"
2. 事件处理：
   • 优先使用 UI5 事件方法
   • 谨慎使用 preventDefault()
3. 响应性：用户操作应得到即时反馈
4. 长操作：使用 BusyIndicator 提示

渲染器最佳实践

1. HTML结构：
   • 每个控件必须有且只有一个根元素
   • 生成语义化的 HTML5
2. 安全防护：对未知字符串进行 HTML 转义
3. ID生成：子元素 ID 格式为 <controlID>-<suffix>
4. 必要调用：
   • RenderManager.writeControlData() 必须在根元素调用
   • RenderManager.writeClasses() 必须在根元素调用

主题与 CSS 规范

通用规则

1. 单位选择：
   • 使用 rem 作为主要单位
   • 仅在字体无关的尺寸上使用 px
2. 布局控制：
   • 根元素不加外边距
   • 内边距加在内部元素
3. 颜色定义：使用 LESS 参数而非硬编码
4. 选择器规范：
   • 避免通用选择器(*)
   • 所有选择器必须包含 UI5 特定类

命名约定

1. 前缀规则：
   • 核心控件：sapUi
   • sap.m 库：sapM
2. 控件特定类：
   • 根元素类：sapUiBtn (Button 示例)
   • 子元素类：sapUiBtnInner

上下文样式

通过父控件添加标记类实现子控件样式调整：

/* 父控件定义标记类 */
.sapUiTable-CTX { /* 无样式，仅作标记 */ }

/* 子控件响应样式 */
.sapUiTable-CTX .sapUiInput {
    border: none;
}

工具与验证

1. ESLint：强制执行代码风格检查
   • 配置应符合项目规范
   • 提交前必须通过检查
2. 编辑器配置：
   • 确保使用制表符缩进
   • 设置 UTF-8 编码

总结

遵循这些规范将帮助你编写出更专业、更易维护的 OpenUI5 代码。记住，规范的核心目标是保持代码的一致性和可读性，特别是在大型企业应用中，这些品质尤为重要。当遇到特殊情况时，应以代码清晰度和维护性为首要考虑因素。

openui5 OpenUI5 lets you build enterprise-ready web applications, responsive to all devices, running on almost any browser of your choice. 项目地址: https://gitcode.com/gh_mirrors/op/openui5