Ratchet

用简单的 HTML, CSS, 和 JavaScript 组件创建移动应用

Ratchet

GitHub Release Build Status devDependency Status

Build mobile apps with simple HTML, CSS, and JS components.

Table of contents

Getting started

  • Clone the repo with git clone https://github.com/twbs/ratchet.git or just download the bundled CSS and JS
  • Read the docs to learn about the components and how to get a prototype on your phone
  • Check out examples

Take note that our master branch is our active, unstable development branch and that if you're looking to download a stable copy of the repo, check the tagged downloads.

What's included

Within the download you'll find the following directories and files, logically grouping common assets and providing both compiled and minified variations. You'll see something like this:

ratchet/
├── css/
│   ├── ratchet.css
│   ├── ratchet.min.css
│   ├── ratchet-theme-android.css
│   ├── ratchet-theme-android.min.css
│   ├── ratchet-theme-ios.css
│   └── ratchet-theme-ios.min.css
├── js/
│   ├── ratchet.js
│   └── ratchet.min.js
└── fonts/
    ├── ratchicons.eot
    ├── ratchicons.svg
    ├── ratchicons.ttf
    └── ratchicons.woff

We provide compiled CSS and JS (ratchet.*), as well as compiled and minified CSS and JS (ratchet.min.*). The Ratchicon fonts are included, as are the optional Android and iOS platform themes.

Documentation

Ratchet's documentation is built with Jekyll and publicly hosted on GitHub Pages at http://goratchet.com. The docs may also be run locally.

Running documentation locally

  1. If necessary, install Jekyll (requires v2.5.x).
  2. Install the Ruby-based syntax highlighter, Rouge, with gem install rouge.
  3. From the root /ratchet directory, run jekyll serve in the command line.
  4. Open http://localhost:4000 in your browser, and boom!

Learn more about using Jekyll by reading its documentation.

Documentation for previous releases

Documentation for v1.0.2 has been made available for the time being at http://goratchet.com/1.0.2/ while folks transition to Ratchet 2.

Previous releases and their documentation are also available for download.

Support

Questions or discussions about Ratchet should happen in the Google group or hit us up on Twitter @GoRatchet.

Contributing

Please file a GitHub issue to report a bug. When reporting a bug, be sure to follow the contributor guidelines.

Troubleshooting

A small list of "gotchas" is provided below for designers and developers starting to work with Ratchet.

  • Ratchet is designed to respond to touch events from a mobile device. In order to use mouse click events (for desktop browsing and testing), you have a few options:
    • Enable touch event emulation in Chrome (found in the overrides tab in the web inspector preferences)
    • Use a JavaScript library like fingerblast.js to emulate touch events (ideally only loaded from desktop devices)
  • Script tags containing JavaScript will not be executed on pages that are loaded with push.js. If you would like to attach event handlers to elements on other pages, document-level event delegation is a common solution.
  • Ratchet uses XHR requests to fetch additional pages inside the application. Due to security concerns, modern browsers prevent XHR requests when opening files locally (aka using the file:// protocol); consequently, Ratchet does not work when opened directly as a file.
    • A common solution to this is to simply serve the files from a local server. One convenient way to achieve this is to run python -m SimpleHTTPServer <port> to serve up the files in the current directory to http://localhost:<port>

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, Ratchet is maintained under the Semantic Versioning guidelines. Sometimes we screw up, but we'll adhere to these rules whenever possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major while resetting minor and patch
  • New additions without breaking backward compatibility bumps the minor while resetting the patch
  • Bug fixes and misc changes bumps only the patch

For more information on SemVer, please visit http://semver.org/.

Maintainers

Connor Sears

Created by Connor Sears, Dave Gamache, and Jacob Thornton.

License

Ratchet is licensed under the MIT License.

Ratchet

GitHub Release Build Status devDependency Status

用简单的 HTML, CSS, 和 JS 组件 创建移动应用。

目录

入门

  • 使用命令 git clone https://github.com/twbs/ratchet.git 克隆版本库或者直接 下载 CSS 和 JS
  • 阅读文档 学习组件,以及如何在你的手机上得到一个原型。
  • 查看示例

需要注意的是,我们的 master 分支是活动的,不稳定的开发分支,如果你正在寻找下载版本库的稳定版本,请查看 tagged downloads

包含的文件

在下载包内,你可以发现下面的文件夹和文件,公共资源的逻辑分组,并且提供了编译和压缩的变化,你会看到类似这样的:

ratchet/
├── css/
│   ├── ratchet.css
│   ├── ratchet.min.css
│   ├── ratchet-theme-android.css
│   ├── ratchet-theme-android.min.css
│   ├── ratchet-theme-ios.css
│   └── ratchet-theme-ios.min.css
├── js/
│   ├── ratchet.js
│   └── ratchet.min.js
└── fonts/
    ├── ratchicons.eot
    ├── ratchicons.svg
    ├── ratchicons.ttf
    └── ratchicons.woff

我们提供编译后的 CSS 和 JS (ratchet.*), 以及编译和压缩后的 CSS 和 JS (ratchet.min.*)。包含了 Ratchicon 字体, 作为 Android 和 iOS 平台主题的选择。

演示

awesomes-cn awesomes-cn awesomes-cn

文档

Ratchet 的文档是用 Jekyll 生成的,公开托管在 GitHub 上 http://goratchet.com。文档也可以在本地运行。

本地运行文档

  1. 如果需要, 安装 Jekyll (要求 v2.5.x).
  2. gem install rouge 安装基于 Ruby 的语法高亮, Rouge
  3. From the root 从根目录下的 /ratchet 文件夹在命令行中执行 jekyll serve
  4. 在浏览器中打开 http://localhost:4000

阅读 Jekyll 的 文档 学习更多关于使用 Jekyll 的知识。

以前版本的文档

当过渡到 Ratchet 2 的时候,1.0.2 版本的文档在 http://goratchet.com/1.0.2/ 上可以获取到。

以前的版本 和他们的文档也是可以下载的。

支持

关于 Ratchet 的问题和讨论可以上 Google group 或者在 Twitter @GoRatchet 上和我们互动。

贡献

请将 Github issue 提交到 报告bug。当报告一个 bug 时,确定遵循了 贡献者指南

疑难解答

下面是为设计师和开发人员开始使用 Ratchet 准备的一个陷阱小清单。

  • Ratchet is designed to respond to touch events from a mobile device. In order to use mouse click events (for desktop browsing and testing), you have a few options:
    • Enable touch event emulation in Chrome (found in the overrides tab in the web inspector preferences)
    • Use a JavaScript library like fingerblast.js to emulate touch events (ideally only loaded from desktop devices)
  • Script tags containing JavaScript will not be executed on pages that are loaded with push.js. If you would like to attach event handlers to elements on other pages, document-level event delegation is a common solution.
  • Ratchet uses XHR requests to fetch additional pages inside the application. Due to security concerns, modern browsers prevent XHR requests when opening files locally (aka using the file:// protocol); consequently, Ratchet does not work when opened directly as a file.
    • A common solution to this is to simply serve the files from a local server. One convenient way to achieve this is to run python -m SimpleHTTPServer <port> to serve up the files in the current directory to http://localhost:<port>

版本控制

For transparency into our release cycle and in striving to maintain backward compatibility, Ratchet is maintained under the Semantic Versioning guidelines. Sometimes we screw up, but we'll adhere to these rules whenever possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major while resetting minor and patch
  • New additions without breaking backward compatibility bumps the minor while resetting the patch
  • Bug fixes and misc changes bumps only the patch

For more information on SemVer, please visit http://semver.org/.

维护人员

Connor Sears

由 Connor Sears, Dave Gamache, 和 Jacob Thornton 创建。

许可

Ratchet 是在 MIT License 下许可的。

讨论区