Canvas Best Practice 1.1.0

Canvas最佳实践指南旨在帮助您构建使用Canvas for TM1的应用，这些应用易于维护并充分利用Canvas的所有功能。本指南涵盖了一些关键原则：

• 一致性即质量！
• 可读性比减少按键更重要。
• 所有名称（变量、类名等）应描述其用途。
• 对任何不明显的内容进行注释。

目录

• 通用规则
• HTML
• 样式（CSS）
• JavaScript
• HTML或控制器中的逻辑？
• 优化性能

通用规则

• 使用一致的名称和大小写使您的代码更易于理解。
• 始终使用/admin控制台中的页面创建器来创建新页面。
• 它将创建一个HTML页面和JavaScript控制器。
• 对简单操作使用内联代码。
• 为更复杂的代码创建$scope函数，以便于调试或在页面中重用。
• 避免使用$root作用域在页面之间传递参数。
• 使用状态参数在页面之间传递简单值。
• 在页面中每次进行选择时更新URL查询参数。这对于PDF创建很重要。
• 尽可能使用Bootstrap，以保持外观和感觉的一致性，并允许在主题之间切换。
• 不要使用JQuery，即$(".class")...，而应使用Angular 1指令。JQuery与Angular应用的兼容性不佳。

HTML

• 所有HTML元素、属性和ID应为小写。
• 在值中使用连字符分隔单词：id="myElement"变为id="my-element"。
• 使用2个空格作为缩进（VS Code中的默认设置）。
• 始终在父元素内缩进子块。
• 使用空行分隔逻辑代码块。
• 对于具有多个属性的元素，每个属性应放在一行（缩进）上，而不是一行。
• 元素属性值始终使用双引号。
• 唯一例外是tm1-elements属性，对于此属性最好使用单引号，以便元素可以用双引号限定。

样式

• 不要使用<table>元素来布局您的页面。
• 使用Bootstrap的class="col-md-4"类，使您的页面适应不同的浏览器大小。
• 使用Bootstrap类对所有可视元素进行样式设置：表格、按钮、输入、选择、标签等。
• 限制在元素上使用style属性的使用。
• 如果在两个或多个元素上重复使用特定样式，请将其设为CSS类。
• 在创建自己的样式之前，尝试使用Bootstrap样式。这将使您可以轻松更改主题。
• 将特定页面的样式放置在页面顶部的<style>元素中。
• 如果在多个页面上使用CSS类，请将其放置在\css\style.css中。
• CSS类名应为小写，单词之间用连字符分隔：warning-message

JavaScript

• 始终缩进您的代码块，即if、for等。
• 使用两个空格作为缩进（VS Code中的默认设置）。
• 使用空行分隔逻辑代码块。
• 使用空格和多行增加可读性。
• 所有代码块始终使用大括号。

命名约定

• 所有变量应使用驼峰式命名法。
• 应使用单数和复数变量名。
• 所有变量应按Angular最佳实践封装在一个对象中。
• 变量的标准分类如下：
  • defaults.* 是声明一次并在页面中更改的变量，否则称为编程语言中的常量。这包括：
    • 在HTML或JavaScript中硬编码的静态字符串/值，即defaults.instance = "dev"。
    • 从dbr返回并在整个页面中使用的当前月份和年份等变量。
  • lists.* 应用于存储与ng-repeat一起使用的任何列表，即tm1-ui-element-list。
  • selections.* 应用于存储用户在页面中所做的所有选择。包括：
    • 用于页面的标题维度。
    • 功能如零抑制、文本搜索和隐藏/显示部分，即Q1、Q2等。
    • 更改页面外观和感觉的任何其他选项，即月度、季度视图。在URL中，即显示/隐藏页面中的元素。
  • values.* 应存储任何dbr、dbra或其他从服务器获取的值，以便在其他地方使用，即在计算中使用。
• 在显示和隐藏页面元素时，应通过名称指示其功能，记住所有变量的默认值为false，即null也是false。示例：
  • 默认隐藏的元素：ng-if="options.showDetail"
  • 默认显示的元素：ng-if="options.hideDetail"
• 不要在变量名前加前缀以指示作用域或数据类型。
• 所有$scope级别的变量应是对象的一部分。
• 代码应按以下顺序排列：
  1. $scope级别的变量
  2. 任何函数
  3. 任何初始化代码，即对服务器的请求。

HTML或控制器中的逻辑

在开发您的第一个Canvas应用时，您可能会问的一个问题是何时使用内联JavaScript或将页面逻辑添加到控制器中。Canvas的设计旨在减少需要编写的代码量。它为您做了大部分繁重的工作，您需要决定的是您和同事开发人员是否可以轻松维护和理解代码。

本节将概述两种方法的优缺点。您可能会根据逻辑的复杂性和是否需要重用而使用这两种方法。

何时使用内联JavaScript的简单规则：

• 如果您的逻辑简单，只有一两个命令。这将适用于大多数逻辑片段。
• 如果代码不需要在页面的多个位置使用。

何时使用$scope函数的简单规则：

• 如果逻辑复杂或需要条件语句或循环。
• 如果逻辑片段需要重用。
• 如果您在页面中遇到问题，需要调试您的逻辑。
• 如果您需要访问JavaScript库和函数。

优化性能

性能是任何应用的重要考虑因素。Canvas设计易于使用，即使对于编程背景有限的人也是如此。Canvas隐藏了大部分困难的部分，让您专注于页面设计和功能。这并不意味着您可以简单地设置和忘记页面上的内容，浏览器能够快速处理的内容量是有限的。

在我们概述最佳实践之前，有必要描述Canvas的工作原理及其优缺点。Canvas页面由一系列Angular指令组成，这些指令向TM1服务器和其他指令发送信息。以下是一个非常简单的页面的示例：

• 限制页面上DBR的数量，少于1,000个。
• 使用分页和ng-if的组合来限制页面上的内容量。
• 按需显示的动态部分应切换ng-if。
• 模态和对话框内容在需要之前应使用ng-if="false"移除。
• 对于具有大量行的请求，考虑使用命名MDX语句和$tm1Ui.resultsetTransform()代替DBR。

通过遵循这些最佳实践，您可以确保您的Canvas应用不仅易于维护，而且性能卓越。