diff --git a/zh-Hans-CN/README.md b/zh-Hans-CN/README.md new file mode 100644 index 0000000..091eb73 --- /dev/null +++ b/zh-Hans-CN/README.md @@ -0,0 +1,68 @@ + +#Enyo.js API 参考生成器 + +本项目的目的是为 [enyo](https://github.com/enyojs/enyo) 和它的[公共库](https://github.com/enyojs)积累和生成 API 参考文档。这个目的可以通过已有的技术力量,包括enyo自己, 根据那个时候要求自己编写的局限性。 + +> 这个项目的最终目的是协调所有文档和开发指南,让它们整合在一个统一的,标准化的和内聚的源内,这个源可展示,可扩展,可理解。今后,[我希望](https://github.com/clinuz) 这个项目能更好地满足这个目的。目前为止,这个愿望不可能实现。 + +### 系统要求 + +开发者指南要求 Unix 类的 shell。如果你希望创建完整的文档,你需要 Linux 或者 Mac OS X。如果你想冒险,你可以把 shell 任务转换成 grunt 任务(可能用 grunt-pandoc 或者 pandoc node 模块)。 + +### 技术 + +##### 要求的核心技术 + +- [Node.js](http://nodejs.org/) - 有关 `node` 的所有东西 +- [npm](https://www.npmjs.org/) - [Node.js](http://nodejs.org) 的包管理(已经与node一起安装) +- [pandoc](http://johnmacfarlane.net/pandoc/) - 通用文档转换工具,用来将 markdown 文件转换成 HTML 文件。确保它在你的可执行路径中。(小窍门:在 Mac里用 'brew install pandoc') + +##### 要求全局 npm + +- [Grunt.js](http://gruntjs.com/) - 命令行客户端: `npm install -g grunt-cli` +- [Bower](http://bower.io/) - 依赖管理工具: `npm install -g bower` + +##### 集成技术 + +在 *enyo-docs* 目录下运行 `npm install` 然后 `bower install` 来安然更多需要的东西。 + +- [JSdoc3](http://usejsdoc.org) - 本文档最主要的语法和解析/生成工具 +- [Nunjucks](http://mozilla.github.io/nunjucks/) - 模板引擎,用于生成静态 HTML 内容 +- [Grunt.js](http://gruntjs.com/) - 任务运行器,用来帮助自动生成和创建网站那部分 +- [Prism.js](http://prismjs.com/) - 在输出时用的代码/语法高亮工具 +- [JQuery](http://jquery.com/) - 作为运行时的先进增强JavaScript库,用于静态 DOM 的交互 + +### 文件系统设定 + +enyo-docs 脚本假定 enyo 和它的库是兄弟关系,库是在 *lib* 目录中,像 Bootplate 标准的方式。换句话说: + +``` +Parent ++- enyo-docs ++- enyo ++- lib + +- onyx + +- layout + +- moonstone + +- canvas + +- spotlight +``` + +被扫描的目录(和其它 jsDoc 选项)可以在 *jsdoc-conf.json* 里发现。 + +### 创建文档 + +为了创建文档,简单地在 *enyo-docs* 目录中运行 grunt: + +``` +grunt +``` + +生成的文档会在 *output* 目录内。 + +### 更多注解 + +两个特别的 'macros' 会用在 enyo 文档源中: + +* `$api` - 转换成文档根目录相对位置。主要用在 developer-guide 里定位 api 参照。 +* `$dev-guide` - 转换成开发者指南的相对位置。主要用于在 enyo 源内指向开发者指南的文章。 diff --git a/zh-Hans-CN/developer-guide/design.md b/zh-Hans-CN/developer-guide/design.md new file mode 100644 index 0000000..9a790ff --- /dev/null +++ b/zh-Hans-CN/developer-guide/design.md @@ -0,0 +1,12 @@ +% 设计指南 + +我们很高兴地提供下面的资源给开发者,他们使用 Enyo UI 和 Moonstone UI 框架库来 +设计应用: + +* [设计原则](design/principles.html) + +* [UI 模式](design/patterns.html) + +* [UI 控制](design/controls.html) + +* [风格](design/styles.html) diff --git a/zh-Hans-CN/developer-guide/getting-started/bootplate.md b/zh-Hans-CN/developer-guide/getting-started/bootplate.md new file mode 100644 index 0000000..6d55bbf --- /dev/null +++ b/zh-Hans-CN/developer-guide/getting-started/bootplate.md @@ -0,0 +1,214 @@ +% Bootplate + +enyojs 项目包括一套注用模板,称为 "Bootplate" (BOOTstrap + boilerPLATE) 模板。 +它们既可以用于创建新项目,也可以用于布署最终项目。 + +## Bootplate 快速启动 + +两个 Bootplate 模板有各自的 GitHub 仓库(例如: +[bootplate](https://github.com/enyojs/bootplate) 和 +[bootplate-moonstone](https://github.com/enyojs/bootplate-moonstone)), +我们提供两个简单的方法来使用 Bootplate,都不需要直接使用 Git。 + +### generator-enyo + +我们推荐使用 `generator-enyo` 来开始 Bootplate 应用。它用 +[Yeoman](http://yeoman.io/) 来实现这个功能。Yeoman 是一个开源的 Web 开发工具 +套件。 + +**注:** 使用 `generator-enyo`前,你首先需要确定 + [Node.js](http://nodejs.org) 和 + [Node 包管理器](https://npmjs.org) 已经安装在 Mac OS 或 Linux 电脑里。 + +1. 使用 Node Package Manager `(npm)` 来安装 `generator-enyo`: + + ``` + sudo npm install -g generator-enyo + ``` + + 注意,如果 Yeoman 没有没有安装,会先安装它。(同时也要注意 `sudo` 不是在所有 + 平台上都是必需的。) + +2. 运行生成器,指定你的新应用的名字: + + ``` + yo enyo + ``` + + 这会创建 `` 目录并在里面生成 Enyo 应用需要的文件。缺省包含 Onyx UI + 库;想要选择不同的 UI 库,用 `-m` 或 `--mode` 选项,如: + + ``` + yo enyo -m=moonstone + + yo enyo --mode=moonstone + ``` + +### 另外的方法 + +1. 从[enyojs.com](http://enyojs.com/get-enyo/)下载 bootplate zip 文件,解压缩并 + 打开 `bootplate-moonstone` 文件夹(对于 Onyx 版本来说是 `bootplate` 文件夹)。 + +2. 在浏览器中载入 `debug.html` 然后看 "Hello World"。 + +## 开发 + +到这里,你可以从模板提供的 `source/app.js` 文件来开始普通的开发、测试循环。随着应 +用增长,它会包括越来越多的 JavaScript 和 CSS 文件,还包括自带 `package.js` 文件 +的库,别忘了把这些包括在你顶级的 `source/package.js` 文件中。 下面将要提到 +的 `deploy` 脚本会为了布署而整合他们进入优化过的 JavaScript 和 CSS 文件中。 + +出于本章的目的,让我们假设你已经完成了所有 "HelloWorld" 应用的工作,准备把注意力 +移到布署流程上来了。 + +现在你应该通过普通的开发和测试流程来改进你的项目,可以从模板提供的 `source/app.js` +文件开始。随着应用的增长,会包括越来越多的 JavaScript 和 CSS 文件,还有包括有自己 +`package.js` 的库,要确保在顶级 `source/package.js` 里包括这些内容,下面的 +`deploy` 脚本会把它们都组合进优化的 JavaScript 和 CSS 文件里用来布署。 + +出于本文章的目标,让我们假设已经完成了 “HelloWorld”应用,把注意力转到布署的 +流程上来。 + +## 开发 + +### 用 generator-enyo + +安装 `generator-enyo` 的一个优点就是可以让布署应用变得异常容易。只要进入应用目录 +然后执行命令: + +``` + yo enyo:deploy +``` + +在 `deploy` 这个目录里会创建优化后的应用。 + +你的项目现在已经准备好布署到不同的 HTML5 可用的目标上。想要知道如何布署应用到 +特定的平台,见 [特定平台布署](../deploying-apps/platform-specific-deployment.html). + +### 另一种方法 + +如果你不用 `generator-enyo`,用下面的步骤布署应用: + +1. 确认你已经在系统里安装了 node.js 。为了让布署脚本运行,你需要 0.8 或以上版 + 本。你可以从 [nodejs.org](http://nodejs.org) 下载。 + +2. 用如下的办法生成布署方案: + + * 打开命令窗 (Windows) 或 终端 (Mac/Linux). + + * 在命令行,进入 bootplate 文件夹的根。 + + * 运行 `tools\deploy.bat` 脚本 (Windows) 或 `./tools/deploy.sh` (Mac/Linux)。 + + (注:在2.1.1版之前,进入 `tools` 文件后运行 `deploy.bat` 或 `./deploy.sh`) + +当构建完成,在 `build` 这个目录下,会有两个压缩的 JavaScript 文件,两个压缩的 +CSS 文件;`app.js` 和 `app.css` 包含你的应用代码, `enyo.js` 和 `enyo.css` +包含框架代码。 + +`build` 文件夹和其它一套补充文件(`index.html` 文件载入你的应用,应用使用的任 +何图像或者其它资源等)复制到最终的布署文件夹 `deploy`。 + +3. 打开布署文件夹,在浏览器中载入 `index.html` ,会看到 "Hello World" (但是很快!)。 + +现在你的项目为不同的 HTML5 可用的目标作好布署的准备。关于在特定平台上布署应用的 +细节,可以参见[特定平台布署](../deploying-apps/platform-specific-deployment.md)。 + +1. 确定你的系统里已经安装 Node.js 运行时(0.8或更新版)。 + +2. 按以下方法制造布署版: + + * 打开命令行(Windows)或者终端窗口(Mac/Linux)。 + + * 在命令行上转到 bootplate 文件夹的根目录。 + + * 运行 `tools\deploy.bat` 脚本(Windows)或者 `./tools/deploy.sh` + (Mac/Linux). + + 当建造完成后,在 `build` 目录下会有两个压缩过的 JavaScript 文件和两个压缩过 + 的 CSS 文件;`app.js` and `app.css` 包含应用的代码, `enyo.js` 和 `enyo.css` + 包含框架代码。 + + `build` 文件夹和相关的一套文件(`index.html` 文件用来载入应用,任何图像或 + 其它应用使用的资源等)复制到最终的布署文件夹 `deploy` 中。 + +3. 打开 `deploy` 文件夹,在浏览器中载入 `index.html` 可以年到 "Hello + World" (但是更快)。 + +## 有关 Bootplate 项目更多的说明 + +### 嵌入的 Enyo + +设置 Bootplate 项目来使用_嵌入的_ Enyo。换句话说, Enyo 库和其它依赖项完全储存 +在项目文件夹内。这些资源相对小,并把所有依赖项放在一起,这样可以让开发者控制版 +本,也可以轻易布署封装好的包(如:PhoneGap 建造)。 + +### 开发与布署 + +当开发和查错时,会需要各种各样的源文件和辅助工具,这些东西在最后的包中并不需要。 +因为这个原因,我们有了造应用_发布_版的概念。一个发布指最终生产用的包,已经可以 +在应用商店中或其它方法发行了。 + +bootplate 一个最要的特性就是你能用相对容易的方法来生成发布版。 + +### 文件夹结构 + +Bootplate 项目有如下结构: + +``` + assets/ + build/ + enyo/ + lib/ + source/ + tools/ + debug.html + index.html +``` + +* `assets` 包含图像或其它你项目的数据文件。在这个文件夹里的文件应该在布署的时 + 候用到。 + +* `build` 包含 JavaScript 和 CSS 源代码文件,它们会交到优化脚本去。如果 `build` + 文件夹不存在,它会在运行 `deploy` 脚本时生成一个。 + +* `enyo` 包含 Enyo 框架源代码方文件。这个文件夹只需要用来查错,可能会为布署而 + 删除。 + +* `lib` 包含不同的插件文件。在 `lib` 中不同的文件夹可能来自不同的源,也许有为 + 布署定制的规则。总得来说, `assets` 或 `images` 文件夹是需要的,其它文件 + 夹只为查错用。 + +* `source` 包含源代码文件或其它只用于查错的材料。 + +* `tools` 包含 `deploy` shell 脚本。 + +* `debug.html` 载入没有任何建造文件的应用;载入 `debug.html` 是查错最简单的方法。 + +* `index.html` 只载入使用建造文件的应用。如果建造文件不能用,它会重定位到 + `debug.html`. + +### 更新框架代码 + +`generator-enyo` 使用每个 Bootplate 模板最新的稳定版。(每个版本的 Bootplate +参考特定的 Enyo 核心版和相应的库。)当新的稳定版出来时,`generator-enyo` 工具 +特定的 Bootplate 版会更新。 + +检查 `generator-enyo` 更新可以用命令 + +``` + sudo npm update -g generator-enyo +``` + +如果更新版被发现并安装,通过进入应用目录并执行以下命令,你可更新框架代码 + +``` + yo enyo:update +``` + +(注意 `generator-enyo` 支持很多附加选项,我们会在短期内写入文档。) + +**附加读物** + +* [Moonstone 应用教程](moonstone-app-tutorial.html) +* [特定平台的开发](../deploying-apps/platform-specific-deployment.html) diff --git a/zh-Hans-CN/developer-guide/getting-started/enyo-tour.md b/zh-Hans-CN/developer-guide/getting-started/enyo-tour.md new file mode 100644 index 0000000..b67ca69 --- /dev/null +++ b/zh-Hans-CN/developer-guide/getting-started/enyo-tour.md @@ -0,0 +1,111 @@ +% Enyo: 简明教程 + +感谢下载Enyo!本文档帮助你熟悉这个框架是怎么组成的以及各个部分提供了什么。 + +在一个 Enyo 发行版中,你会发现如下文件夹: + +* **enyo** - 核心 +* **lib** - 所有插件,附加库放置的地方 +* **moonstone** - UI 组件工具箱,为电视优化过 +* **onyx** - Enyo 最初的 UI 库,为移动设备优化过 +* **spotlight** - 一个控制焦点状态的专用库 +* **layout** - 布局组件集合 +* **enyo-ilib** - 提供本地化服务的库 +* **canvas** - 用于生成基于 HTML5 canvas 视图的组件 +* **extra** - 增加的工具组件 + +## Enyo + +框架核心,在源码中简单认为是 `enyo`,它提供了强大的特性来开发复杂的应用和附加库, +这些都是以模块化的 Web 栈基础之上的: + +* **对象封装,继承,有等级的所有权** - 类和组件(Kinds and Components) +* **视图和DOM插件模型** - Ui组件和控制(UiComponent and Control) +* **事件路由** - 分发和信号(Dispatcher and Signals) +* **服务器模型** - Async and Ajax +* **基础的 HTML 组件** - 基础用户界面(Base UI) +* **触摸支持** - 触摸滚动和手势仿真 +* **包载入** - `enyo.depends()` 和 `package.js` + +这些部分实际上是分享的(它可以很容易地创建小型 Enyo),但我们相信它们形成了一个有 +用的工作集合,所以我们把它们作为 Enyo 核心呈现给大家。 + +以下所有东西都是基于核心的可选项。可以根据你应用的需要选择。不过,这些只是一个参 +考库,我们会有一个大生态圈,那里的插件可能会有不同的外观和感觉,布局选项,服务封 +装等。请到 [Enyo 社区像册](http://enyojs.com/gallery)去看看创建和分享一个组件或 +插件库是多么容易的事。 + +## Moonstone + +Moonstone 库提供了一个美化过的图形界面组件,它特意为电视应用进行了设计和优化。 +它正在扩展,目前包括: + +* **按钮**(普通,图标,收音机按钮和触发按钮) +* **输入**(文本输入框,文本输入区域,富文本输入区域) +* **列表** +* **弹出菜单** +* **标题栏** +* **分组框** +* **进度条** +* **滑块** + +## Onyx + +Onyx 是原先和 Enyo 一起发布的UI库,对于移动设备应用,还是保持用这个库。虽说近期主 +要是在发布 Moonstone , 但新的 Onxy 开发也在进行中。我们鼓励你到 +[Onyx 源](https://github.com/enyojs/onyx) 查看一下,并保持最新姿态。 + +## Spotlight + +Spotlight 库管理焦点状态,它能够让用户在五向模式(用键盘的方向键和回车键,或者传 +统的电视遥控器上的相应按钮)或指点器模式(用鼠标或触摸屏)下浏览 Enyo 应用。 + +## Layout + +Enyo 组件也许可以用纯 HTML/CSS 技术来布局,我们提供的布局库让你更容易,更高效而且 +跨浏览器地解决布局的需要: + +* **自适应的行和列** +* **列表** +* **面板** + +你可以在[这](https://github.com/enyojs/layout)看到有关布局的选项。 + +## enyo-ilib + +`enyo-ilib` 库给 Enyo 框架进行本地化提供了支持。主要的工作由开源库 `iLib` 完成。 +`enyo-ilib` 主要作为兼容层来使 Enyo 应用的开发人员更轻松地使用 `ilib` 的强大 +特性,同时不需要处理很多与本地化相关的细节。 + +## 画布(Canvas) + +Enyo 封装同样适用于以画布为基础的组件,它像传统UI一样工作,我们提供了一个库抽象了画布的通用功能象 Enyo 组件: + +* **画布和画布控制** +* **形状**(圆,矩形) +* **文本** +* **图像** + +你可以轻松地扩展这些来创建复杂的图形应用和游戏,比如我们的 +[Pirate Pig](http://enyojs.com/samples/piratepig) 画布示范应用。 + +## 扩展(Extra) + +"extra" 扩展库包括了一些有用的工具组件,范例中使用了这些组件。 + +## 开始(Bootplate) + +[Bootplate](bootplate.html) 模板,它给开发新 Enyo 应用提供了一个完整的解决方案。 +这些模板包含在当前的 Enyo 发行版中,同时还包含了应用开发人员最常用的库 +(Moonstone 或者 Onyx,Layout等),也包括了一些脚本用来最小化和创建源码和附件的 +发布版。 + +## 阅读更多 + +* 如果你喜欢一步一步介绍 Enyo,这里是 [Moonstone 应用教程](moonstone-app-tutorial.md)。 + +* 立即写 Enyo 应用,去 [Bootplate](bootplate.md)。 + +* 了解更多 Enyo 应用结构细节,看[计划和组织应用](planning-and-structuring-your-app.md)。 + +* 还不能满足你?看当前文档的[全部列表](../index.md), diff --git a/zh-Hans-CN/developer-guide/getting-started/first-steps.md b/zh-Hans-CN/developer-guide/getting-started/first-steps.md new file mode 100644 index 0000000..fcc9ddf --- /dev/null +++ b/zh-Hans-CN/developer-guide/getting-started/first-steps.md @@ -0,0 +1,104 @@ +% 与 Enyo 的第一步 + +## 准备开发环境 + +作为 Enyo 开发者,你有很大的自由去选择开发平台和工具来写你的应用代码。你可能在 +Windows, Mac, 或者 Linux 环境。仅需要一些简单的工具就可以弄好并运行了。 + +### 文本编辑 + +写 Enyo 代码,只需要文本编辑器。任何一种编辑器都足够用,包括基础的自由软件如 +[Notepad++](http://notepad-plus-plus.org/)(Windows)或者 +[TextWrangler](http://www.barebones.com/products/textwrangler/)(Mac)。 +对那些物有所值的软件,Enyo 团队倾向用 [Sublime Text](http://www.sublimetext.com/), +该软件可在 Mac 和 Windows 下使用,或者只能在 Mac 下使用 +的 [TextMate](http://macromates.com/)。 + +### Git 客户端 + +目前发行 Enyo 核心、库和“bootplate" 用的主要是 GitHub,所以你需要有现代的 Git +客户端安装在机器里。在本文档里,我们用 git 命令行,但你也可以使用喜欢的图形界面 +git 客户端。 + +你可以在 [git-scm.com](http://git-scm.com/downloads)下载你的操作系统对应的 git +客户端。 + +(注意:Enyo "bootplate" 模板同样在 **LG webOS TV SDK** 中一起分发,它可能使用 +在 SDK 中的 `ares-generate` 命令生成,该命令不需要 Git。 如果使用 +**LG webOS TV SDK** ,而且不打算在你的应用中用 Git 来控制版本,你不需要安装 +Git 客户端。) + +### Node.js + +Enyo 框架包含了基于 `Node.js` 的工具用来最小化和布署应用。 `Node.js` 是服务器端 +的运行时(像是服务器端的 Perl, Python, Ruby 和其他语言的解释器)用于在服务器上运 +行 JavaScript 脚本。甚至可以只用 `Node.js` 本身作为主 Web 服务器(下面会看到)。 + +可以在 [nodejs.org](http://nodejs.org/) 下载你的操作系统对应版本的 `node.js`。 + +### Web 浏览器和 Web 服务器 + +在开发过程中,你可以用任何现代浏览器来测试你的代码。也许在浏览器中可以直接打开本 +地文件,但我们还是强烈建议你通过 HTTP 服务器来打开应用。这个建议有很多好处,其 +中包括有能力从远程设备进行测试。 + +在 Web 服务器上运行你的应用可以避免 Chrome 浏览器对 AJAX 的安全限制。如果想选择 +在 Chrome 开发,*并且*直接从文件系统打开你的文件,你需要在命令行启动浏览器并加 +上 `"--allow-file-access-from-files"` 这个参数。(在Windows中,你可以创建一个 +快捷链接到 `Chrome.exe` ,并把这个参数放在快捷链接的目标属性中。然后每次运行浏览 +器的时候都使用这个快捷链接。在 Mac 和 Linux 中有类似的解决办法。) + +如果你目前没有运行本地 Web 服务器,你会发现安装 Apache/MySQL/PHP 软件套装很方 +便,比如 [BitNami WAMPStack](http://bitnami.org/stack/wampstack) (Windows) +或者 [MAMP](http://www.mamp.info/en/index.md) (Mac)。 + +像前面提到的,另外一个解决办法是用 `Node.js` 来创建自己的简单 HTTP 服务器。 +下面告诉你怎么做: + +* 安装 `Node.js`。 + +* 用 npm 安装 `serve` 包: + +``` + npm install -g serve +``` + +* 创建一个目录用于存放服务器的脚本,进入该目录,然后运行 `serve` 来启动服务器, +例如: + + + `mkdir ` + + `cd ` + + `serve` + +* 可以从 3000 端口来接入你的应用,用 URL 可以是 `http://localhost:3000/debug.html`。 + +## 获取 Enyo 源代码 + +### Bootplate + +如果你是 Enyo 开发的新人,你会希望把 Enyo 源代码作为现成的项目模板的一部分。 +这个 enyojs 项目包括这样一些我们称为 "bootplate" (BOOTstrap + boilerPLATE) 模板 +的东西。每个 bootplate 模板会有 Enyo 核心代码,一个或多个与项目相关的库,一个 +“你好世界”这种应用,和一个推荐的文件夹结构用来组织本应用中的文件。关于 +bootplate 模板,包括设置介绍,见[Bootplate:在5分钟内用 Enyo 从0到60](bootplate.md)。 + +想用 Moonstone UI 库来启动应用,克隆 `bootplate-moonstone` 仓库到本地机器里: + +### 独立的代码仓库 + +当然,你也可以自由克隆 `enyo` 或者任何其它独立的库代码仓库,如: + +``` + git clone https://github.com/enyojs/enyo.git +``` + +如果你计划把改变提交回代码库,请确定创建自己的代码仓库分支并在本地机器上克隆这个 +代码仓库分支。 + +## 下一步 + +如果你还没做,请通读 [Moonstone 应用教程](moonstone-app-tutorial.md)。现在你 +有了所有必需的工具,试着按照教程的步骤在你自己的机器里运行这些代码。 + +如果你觉得有困难,或者你想要自己探索,参见 [Bootplate](bootplate.md) 文档中一 +些有用的提醒。 diff --git a/zh-Hans-CN/developer-guide/getting-started/planning-and-structuring-your-app.md b/zh-Hans-CN/developer-guide/getting-started/planning-and-structuring-your-app.md new file mode 100644 index 0000000..9bbfcfc --- /dev/null +++ b/zh-Hans-CN/developer-guide/getting-started/planning-and-structuring-your-app.md @@ -0,0 +1,160 @@ +% 计划和组织应用 + +Enyo 应用会像单页面 HTML5 文件一样简单,但当我们开始开发很炫的应用时,就会有很多 +不同的资源需要管理,版本和信赖项需要跟踪,查错的选项需要控制。为了提供流畅的工作 +流,Enyo 团队对于应用结构接受了一些约定。在 [Bootplate](bootplate.html) 应用模板 + (在 [Moonstone](https://github.com/enyojs/bootplate-moonstone) 和 + [Onyx](https://github.com/enyojs/bootplate) 不同) 中可以看到,我们鼓励你基于 + Bootplate 来开发。这些约定在下面也有详细描述。 + +## 基本的脚手架 + +Enyo 的设计让插件库,应用和 Enyo 自己都可以移动。使用这些通用的文件夹约定可以极大 +地简化资源的管理。 + +推荐的插件库文件夹结构像这样: + + + assets/ + source/ + package.js + (readmes, licenses, nfos) + +* `source` 包含了 JavaScript 模块,样式表,或者给插件的别的原材料 + +* `assets` 典型地包含图像或者其它资源,它们既用在生产环境中,也用在开发/查错中。 + 你可以放任意多的文件夹,文件夹名称也没什么特别的--比如,工程中可能会有 + `images` 和 `json`文件夹。然而,我们建议你把这些项目话一个叫 `assets` + 的文件夹中,这样最终用户马上就能知道这个文件夹在最终布署时是需要的。 + +* `package.js` 是一个清单,列明在这个库里的文件。 + +* `` 文件夹通常包含其它项目,比如读我,许可,或者别的文件。 + +推荐的应用设置也类似,但包括了一些增加项: + + + assets/ + enyo/ + lib/ + build/ + source/ + tools/ + (readmes, licenses, nfos) + debug.html + deploy.json + index.html + package.js + +* `enyo` 文件夹包含 Enyo 框架源代码的复件。像在下面讨论的,可以把 `enyo` 从别 + 的通用的位置引用过来,而不像下面那样嵌入在项目里,但是为了版本和完整性, + 我们建议你在自己的应用中保留一个 Enyo。 + +* `lib` 文件夹包含所有插件或者其它项目中用到的资源。 + +* `build` 文件夹是_最小化后_资源的主目录,这些资源是优化过后的 JavaScript 和 + CSS 文件, 这些文件去除了注释,空格和其它对功能性没有决定性影响的特性。在 + JavaScript 文件里,语法有的时候会变化(例如:变量名称可能缩短)来缩小 + 文件尺寸。 + + `deploy` 脚本运行时会生成最小化的文件。该脚本从 `deploy.json` 中读取配置 + 信息然后激发不同的 `minify` 脚本,它才真正执行优化。(注意,一般情况下是没 + 必要直接调用 `minify`。) + + `deploy` 运行成功后,在 `build` 里的输出有两个 JavaScript 文件(`app.js` + 是你的应用代码,`enyo.js` 是框架代码)和两个相应的 CSS 文件(`app.css` 和 + `enyo.css`)。 + +* `tools` 文件夹放置了上述两个版本的 `deploy` 脚本,`deploy.bat` (用于 + Windows) 和 `deploy.sh` (用于 Mac 和 Linux)。 + + 在开发时,你从 `source` 目录中直接载入应用。(如果你在用 Bootplate模板,你 + 可以载入 `debug.html`。) 当你准备布署应用后,执行 `deploy` 脚本来创建应用 + 的一个版本,该版本的代码最小化同时删除了不重要的文件。 + +## 库文件夹和插件 + +Enyo 的基础设施是倾向能支持各种广泛的插件。这不是技术的要求,这个约定是把插件 +放到一个叫 `lib` 的目录里和 `enyo` 相对应: + + + enyo/ + lib/ + aPluginFolder/ + assets/ + source/ + package.js + (readmes, licenses, nfos) + +再次注意,标准文件结构用于这个插件。 + +## 标准快照 + +如果我们组合两个上面的例子,我会得到完整建议的目录结构: + + + assets/ + build/ + enyo.js + enyo.css + app.js + app.css + enyo/ + lib/ + aPluginFolder/ + assets/ + source/ + package.js + (readmes, licenses, nfos) + source/ + tools/ + debug.html + deploy.json + index.html + package.js + (readmes, licenses, nfos) + +如原来提到的,为组织应用的生产版,复制文件树然后运行 `deploy` 来生成布署版本里面 +去除子开发和查错的资源。缺省情况下,会在叫 `deploy` 中创建这个版本。 + +这是布署树建议的文件结构: + + / + deploy/ + assets/ + build/ + enyo.js + enyo.css + app.js + app.css + lib/ + aPluginFolder/ + assets/ + (licenses) + index.html + +注意 `enyo` 文件夹本身对布署来说不是必需的。 + +## 分享 Enyo + +正如前面提到的,也有可能创建一个应用指向共享的 Enyo 复本和/或插件。这个情况下, +共享的资源通常可以在以下位置找到: + + / + enyo/ + lib/ + aPlugin/ + +下面的结构显示两个应用,两个都从 `` 载入 Enyo 和插件: + + + app1/ + assets/ + source/ + index.html + app2/ + assets/ + source/ + +这种类型的设置主要用在发布插件,创建一套一起布署的应用,或者为 Enyo 源代码 +本身工作。 diff --git a/zh-Hans-CN/developer-guide/index.md b/zh-Hans-CN/developer-guide/index.md new file mode 100644 index 0000000..0f40395 --- /dev/null +++ b/zh-Hans-CN/developer-guide/index.md @@ -0,0 +1,82 @@ +% Enyo 开发者指南 + +欢迎!可用的资源有如下领域: + +* 开始 + + * [Enyo 教程](getting-started/enyo-tour.md) + * [第一步](getting-started/first-steps.md) + * [Bootplate: 5 分种内0-60学会使用 Enyo](getting-started/bootplate.md) + * [计划和组织应用](getting-started/planning-and-structuring-your-app.md) + * [教程:创建 Moonstone 应用](getting-started/moonstone-app-tutorial.md) + +* Enyo 精华 + + * [类型(Kinds)](key-concepts/kinds.md) + * [对象和发布属性](key-concepts/objects-and-published-properties.md) + * [组件](key-concepts/components.md) + * [控制](key-concepts/controls.md) + * [事件控制](key-concepts/event-handling.md) + +* 管理数据 + + * [创建数据驱动的应用](building-apps/managing-data/building-data-driven-apps.md) + * [使用 Web 服务](building-apps/managing-data/consuming-web-services.md) + +* 用户界面布局 + + * [自适应](building-apps/layout/fittables.md) + * [滚动条](building-apps/layout/scrollers.md) + * [列表](building-apps/layout/lists.md) + * [数据列表](building-apps/layout/data-lists.html) + * [抽屉](building-apps/layout/drawers.md) + * [面板](building-apps/layout/panels.md) + +* 创建电视应用 + + * [Spotlight](building-apps/spotlight.md) + * [按钮](building-apps/controls/buttons.md) + * [检查按钮](building-apps/controls/checkboxes.md) + * [头](building-apps/controls/headers.md) + * [列表项](building-apps/controls/list-items.md) + * [选取器](building-apps/controls/pickers.md) + * [弹出菜单](building-apps/controls/popups.md) + * [进度条](building-apps/controls/progress-indicators.md) + * [单选项](building-apps/controls/radio-items.md) + * [文本域](building-apps/controls/text-fields.md) + * [开关](building-apps/controls/toggles.md) + +* 本地化 + + * [本地化](building-apps/localization.md) + +* Enyo 和 webOS + + * [使用 webOS 特性](building-apps/using-webos-features.md) + +* 测试和排错 + + * [基于浏览器的排错](building-apps/testing-and-debugging/browser-based-debugging.md) + +* 布署应用 + + * [平台相关的开发](deploying-apps/platform-specific-deployment.md) + * [在 Windows 8 上的 Enyo 应用](deploying-apps/enyo-apps-on-windows-8.md) + * [Cordova 原生功能](deploying-apps/cordova-native-functions.md) + +* 最佳实践 + + * [API 参考:每一个开发者应该知道](best-practices/api-reference.md) + * [Enyo 能做和不能做的](best-practices/dos-and-donts.md) + * [Enyo 封装](best-practices/encapsulation-in-enyo.md) + * [编码风格指南](best-practices/style-guide.md) + +* 设计应用 + + * [设计指南](design.html) + +* 参考 + + * [API 参考](api.html) + * [Enyo 发布声明](release-notes.md) + * [以前发行版的文档](previous-releases.html) diff --git a/zh-Hans-CN/developer-guide/key-concepts/kinds.md b/zh-Hans-CN/developer-guide/key-concepts/kinds.md new file mode 100644 index 0000000..3ced6c6 --- /dev/null +++ b/zh-Hans-CN/developer-guide/key-concepts/kinds.md @@ -0,0 +1,189 @@ +% Kinds + +## enyo.kind() + +[enyo.kind(inProps)]($api/#/namespace/enyo.kind) 是 Enyo 框架的方法用来生成 +种类。种类是用原型的构造函数(像类),它有一些高级特性,如原型链(继承)。 + +为了扩展种类生成器的能力,包括了一个插件系统,同时当生成子类时,构造函数允许 +执行定制操作。 + +在文本中,我们将看看在调用 `enyo.kind()` 时发生的几件事情。要知道当有一个实 +例化对象后发生了什么,可以看 +[对像和发布的属性](objects-and-published-properties.html) 和 +[组件](components.html). + +## 特殊的属性名 + +通常在传递进的 `inProps` 对象中定义的属性是直接复制到生成的原型中,但是有些属性 +名会触发一些特殊的流程。一些特殊属性的例子如下: + +* `name`: 在全局名字空间(中间对象是自动创建的)定义了创建的构造函数。`name` + 不是直接复制到原型中,它是以 `kindName` 的方式存储。 + + ```javascript + // Create a function myNamespace.MyKind with a prototype. + // myNamespace.MyKind.prototype.kindName is set to "myNamespace.MyKind". + // myNamespace.MyKind.prototype.plainProperty is set to "foo". + enyo.kind({ + name: "myNamespace.MyKind" + plainProperty: "foo" + }); + // Make an instance of the new kind. + var myk = new myNamespace.MyKind(); + ``` + +* `kind`: 从哪里继承的种类名,或者指向这个种类名,象超类。新的构造函数原型会链 + 传递到 `kind` 指定的原型superclass. The new constructor's prototype is chained to the prototype + specified by `kind`, and the `base` property in the new prototype is set to + reference the `kind` constructor. + + ```javascript + // Create a function MyKind with a prototype, derived from enyo.Object. + // MyKind.prototype.kindName is set to "MyKind". + // MyKind.prototype.base is set to "enyo.Object". + enyo.kind({ + name: "MyKind", + kind: "enyo.Object" + }); + ``` + +* `constructor`: An optional function to call when a new instance is created; it + is actually stored on the prototype as `_constructor`. + + ```javascript + // Create a function MyKind with a prototype, derived from enyo.Object. + // _constructor_ is called when an instance is created. + enyo.kind({ + name: "MyKind", + kind: "enyo.Object", + constructor: function() { + this.instanceArray = []; + // Call the constructor inherited from Object + this.inherited(arguments); + } + }); + ``` + +* `statics`: Properties from any `statics` object are copied onto the + constructor directly, instead of the prototype. + + ```javascript + // Create a kind with a static method. + enyo.kind({ + name: "MyKind", + statics: { + info: function() { + return "MyKind is a kind with statics."; + } + } + }); + // Invoke the static info() method of MyKind. + console.log(MyKind.info()); + ``` + +* `protectedStatics`: Introduced in Enyo 2.3, protected statics are statics that + are meant for use only within the kind in which they are declared, or in + code that derives from that kind. + + Unlike public statics, protected statics won't prevent the deferral of a + kind's creation. Deferral is not possible for kinds containing public + statics because of the potential for the public statics' being used before + any instances of the kind exist. + +Certain kinds in the framework define their own special properties, e.g., the +`published` property supported by [enyo.Object]($api/#/kind/enyo.Object). + +## Lifecycle of a Trivial Kind + +A trivial kind has a simple lifecycle: + +```javascript + var MyKind = enyo.kind({ + kind: null, // otherwise it will default to 'Control' + constructor: function() { + // do any initialization tasks + } + }); +``` + +That's it. `MyKind()` is now a function that you can use with the `new` +operator to create instances. + +```javascript + myInstance = new MyKind(); +``` + +Like all JavaScript objects, a kind instance will be garbage-collected when +there are no references to it. + +## Inheritance: this.inherited() + +It's common for one kind to be based on another kind. The new kind inherits all +the properties and methods of the old kind. If the new kind overrides a method +from the old kind, you can call the overridden method using `this.inherited()`: + +```javascript + var MyNextKind = enyo.kind({ + kind: "MyKind", + constructor: function() { + // do any initialization tasks before MyKind initializes + // + // do inherited initialization (optional, but usually a good idea) + this.inherited(arguments); + // + // do any initialization tasks after MyKind initializes + } + }); +``` + +`MyNextKind` starts with all the properties and methods of `MyKind`, but then we +override `constructor()`. Our new constructor may call the old constructor +using the `this.inherited()` syntax. The first parameter passed to +`this.inherited()` must be the literal `arguments`, which is a special +JavaScript variable containing information about the executing function. (For +more about `arguments`, see +[developer.mozilla.org](https://developer.mozilla.org/en/JavaScript/Reference/Functions_and_function_scope/arguments).) + +In its constructor, `MyNextKind` may specify things to do before or after +calling the old constructor, or it may choose to not call the old constructor at +all. + +This override system works the same for any method, not just `constructor()`: + +```javascript + enyo.kind({ + name: "MyOriginalKind", + doWork: function() { + this.work++; + } + }); + + enyo.kind({ + name: "MyDerivedKind", + kind: "MyOriginalKind", + doWork: function() { + if (this.shouldDoWork) { + this.inherited(arguments); + } + } + }); +``` + +Note that you could also call an inherited method using only raw JavaScript, +like so: + +```javascript + MyKind.prototype..apply(this, arguments); +``` + +However, the `this.inherited()` syntax is shorter and eliminates the need to +specify the superkind's name (in this case, `MyKind`). + +**Additional Reading** + +* [Event Handling](event-handling.html) +* [Objects and Published Properties](objects-and-published-properties.html) +* [Components](components.html) +* [Controls](controls.html) + diff --git a/zh-Hans-CN/developer-guide/previous-releases.md b/zh-Hans-CN/developer-guide/previous-releases.md new file mode 100644 index 0000000..10b9590 --- /dev/null +++ b/zh-Hans-CN/developer-guide/previous-releases.md @@ -0,0 +1,6 @@ +% 上一次发布版的文档 + +除了[当前发布版](/docs/)之外,Enyo 前一个发布版的文档也有。注意该信息仅为了 +记录历史的目的。 + +* [Enyo 2.4](/docs/2.4.0/) diff --git a/zh-Hans-CN/developer-guide/release-notes.md b/zh-Hans-CN/developer-guide/release-notes.md new file mode 100644 index 0000000..5aac95f --- /dev/null +++ b/zh-Hans-CN/developer-guide/release-notes.md @@ -0,0 +1,13 @@ +% 发布信息 + +发布信息在以下 Enyo 发行版中: + +* [Enyo 2.5.1 发布信息](release-notes/release-2.5.1.html) (2014年12月11日) +* [Enyo 2.5 发布信息](release-notes/release-2.5.html) (没有公开发行) +* [Enyo 2.4 发布信息](release-notes/release-2.4.html) (2014年4月14日) +* [Enyo 2.3.0-pre.10 发布信息](release-notes/release-2.3.0-pre.10.html) (2013年10月16日) +* [Enyo 2.2 发布信息](release-notes/release-2.2.html) (2013年2月21日) +* [Enyo 2.1.1 发布信息](release-notes/release-2.1.1.html) (2012年11月28日) +* [Enyo 2.1 发布信息](release-notes/release-2.1.html) (2012年10月26日) +* [Enyo 2.0.1 发布信息](release-notes/release-2.0.1.html) (2012年8月30日) +* [Enyo 2.0 发布信息](release-notes/release-2.0.html) (2012年7月18日) diff --git a/zh-Hans-CN/dummy.txt b/zh-Hans-CN/dummy.txt deleted file mode 100644 index 8a78c79..0000000 --- a/zh-Hans-CN/dummy.txt +++ /dev/null @@ -1 +0,0 @@ -Remove me once real files get in here. diff --git a/zh-Hans-CN/enyo-jsdoc-syntax.md b/zh-Hans-CN/enyo-jsdoc-syntax.md new file mode 100644 index 0000000..6a9eff1 --- /dev/null +++ b/zh-Hans-CN/enyo-jsdoc-syntax.md @@ -0,0 +1,22 @@ +### 链接 + +> 我们支持 JSDoc3 标准链接语法的一个子集。 我们不支持所有语法的原因在于它设定了 +> 输出格式,但我们把这部分东西从程序中分享出来。另外的变量对保存预定的输出来说是 +> 多余的。 + +##### 链接到符号 + +- {@link symbol} +- [说明文字]{@link symbol} + +##### 链接到超文本(网页) + +- {@linkplain http://full.path} +- {@linkplain relative/path/to/internal} +- [说明文字]{@linkplain http://full.path} +- [说明文字]{@linkplain relative/path/to/internal} + +##### 术语表 + +- {@glossary term} +- [说明文字]{@glossary term}