理解 Gaia 代码库

在对 Gaia codebase作出您自己的修改之前,您需要理解下Gaia 的基本构成以及使用的编码规则。本文则涵盖了这些这些方面。

Gaia 代码库结构

下面的部分则概述了 Gaia 代码库最重要的部分。

apps/

此目录包括所有的主 Gaia apps, 在 homescreen 中显示的 app(如 calendar 和 camera)和底层 app(如 system, homescreen 和 keyboard ) 。

app 工作方式略有不同,但有许多公共的特点,包括:

  • index.html: 每个 app的中心文件
  • manifest.webapp: 定义 app 的清单文件
  • locales: app 的本地化字符串
  • test: 针对 app 的 单元和集成测试
  • js, style: app 的 脚本和样式
  • resources: 图片,声音以及其他的资源文件

注意: 在 Gaia 应用指南 一文中可获得更多关于 app 工作的内容。

build/

包含编译脚本。

dev_apps/

文件夹中包含自定义的一些应用。例如,您可以包含一些自定义的 app。

注意: 要获取更多关于 Gaia 自定义项的知识,请参考  Market customizations guide.

keyboard/

 keyboard 文件夹包含了 keyboard 词典以及不同语言的布局。

locales/

包含一个 JSON 文件,languages_all.json,  该文件定义了 Gaia 所支持的语言。要更深入的了解 apps 是如何本地化的,请参考  Getting started with app localization.

shared/

此目录包含了多个应用使用的大量的资源文件;其中最重要的部分为:

  • gaia/shared/js:  执行常用功能的 JavaScript 库
  • l10n.js:  是一个本地化库,它会检测您的设备的本地化,使用 app  locales 文件夹下的字符串替换掉您app中的本地化字符串 (Localisable strings)。元素中需替换的本地字符串(Localisable strings)都带有 data-l10n-id 属性.
  • gaia/shared/locales: 不同地域的本地化资源
  • gaia/shared/resources: 常用资源,如图标,铃声和闹钟声音等。
  • gaia/shared/style: 公共控件(如 按钮,进度条,工具栏,表格等)的样式表和其他样式资源。
  • gaia/shared/style_unstable: 不稳定或正在测试的样式资源。
  • gaia/shared/test: 定义集成和单元测试的 JavaScript 代码。

tools/

tools 目录包含编译脚本和测试的工具。

Gaia 编码风格

Gaia 遵循 Google JavaScript coding style.

背景知识:

具体规则

  1. 确保 HTML 文件都带有 <!DOCTYPE html>  声明(也就是 HTML5 文档)。如果您不这么做, Internet Explorer 9 以及后续的版本会以兼容模式来装载它们。
  2. 包含 "use strict"; 这个语句(就像刚才写的一样,包含双引号)放在 Js 文件头部,会使 js 进入 strict 模式。
  3. 使用两个空格来缩进,而不是使用 tabs。
  4. 请使用换行符来分隔代码逻辑!
  5. 多单词的文件名称应该使用下划线字符来分隔单词,如like_this.js
  6. 使用单引号而不是双引号来表示字符串。
  7. 使用扩展的条件结构:
    Bad
    if (expression) doSomething();
    
    Correct
    if (expression) {
      doSomething();
    }
  8. 如果您修改 System app,请阅读  guidance listed here.

每笔提交编码风格检查

在每个 commit 之前,通过调用  git pre-commit hook, Gaia 会使用  jshint 工具会自动对JS 编码风格进行检查。一旦您提交了对 Gaia 仓库的 Pull Request,  Travis (Github Continuous Integration) 服务器会运行这个工具来重复检查样式是否正确。

 precommit hook 脚本在gaia/tools/pre-commit 下,一旦  make 命令执行就会复制到 .git/hooks 文件夹 下。

注意: 我们以前会使用  gjslint 来检查编码风格,但已将其弃用;而是使用 jshint 来产生更严格和更好的效果。从 Firefox OS 1.4 开始就一直使用 JSHint,  gjslint 只被用来检查一些还没有使用 JSHint 的旧文件。

通过 Gaia 来手动运行 linting 检查

在提交 path 前我们推荐您在 patch 上手动运行 JSHint 来检查是否有任何样式上的错误。

您应该在 gaia/build/jshint 目录下获取更多关于 Gaia 中 jshint 的细节;Gaia 为您提供了一个构建脚本,您可运行:

$ make lint

来自动进行 gjshint 和 jshint 样式的检查。 或者您运行

$ make hint

只运行 jshint 样式检查。

注意: 如果您想要在不是用 Gaia 的情况下,自己安装 Jshint,可运行如下命令:

npm install jshint -g
jshint myfile.js

 

文档标签和贡献者

 此页面的贡献者: ReyCG_sub
 最后编辑者: ReyCG_sub,