Opal jQuery 技术文档

本文档将详细介绍如何安装、使用 Opal jQuery，以及如何使用其提供的 API。

1. 安装指南

要安装 Opal jQuery，您可以通过 RubyGems 进行安装：

$ gem install opal-jquery

或者，如果使用 Bundler，可以在 Gemfile 中包含以下代码：

gem 'opal-jquery'

然后运行 bundle install 命令。

2. 项目使用说明

2.1 基本用法

opal-jquery 可以通过标准的 require 方式轻松添加到您的 Opal 应用程序源代码中：

# app/application.rb
require 'opal'
require 'jquery'
require 'opal-jquery'

alert "Hello from jquery + opal"

注意：此文件需要两个重要的依赖项，jquery 和 opal-jquery。您需要自行准备 jquery.js 文件，因为 gem 中不包含。如果使用 Rails 的资产管道，则应该已经可用，否则下载一个副本并将其放入 app/ 或您编译资产的任何目录中。您也可以选择性地要求 Zepto 实例。

#alert 方法由 opal-jquery 提供。如果消息显示，则表示 jQuery 支持应正常工作。

2.2 Opal-jquery 的工作原理

opal-jquery 提供了一个 Element 类，其实例是与 jQuery 对象进行 toll-free 桥接的实例。就像 Ruby 数组只是 JavaScript 数组一样，Element 实例只是 jQuery 对象。这使得与 jQuery 插件的交互变得更加容易。

此外，如果无法找到加载的 jQuery，Element 将尝试与 Zepto 进行桥接，使其非常适合移动应用程序。

3. 项目 API 使用文档

3.1 DOM 操作

查找元素

opal-jquery 提供了 Element 类，可以用来在当前文档中查找元素：

Element.find('#header')

Element.find 方法还有一个别名 Element[]：

Element['.my-class']

这些方法的行为与 $('selector') 相似，并可以使用任何 jQuery 兼容的选择器：

Element.find('#navigation li:last')

结果只是一个 jQuery 实例，它在 Ruby 中桥接为 Element 类的实例：

Element.find('.foo').class
# => Element

Element 实例也提供了 #find 方法，用于在当前 DOM 节点的范围内查找元素：

el = Element.find('#header')
el.find '.foo'
# => #<Element .... >

文档就绪

与 jQuery 一样，opal-jquery 要求文档就绪才能完全与页面交互。任何顶级访问都应该使用 ready? 方法：

Document.ready? do
  alert "document is ready to go!"
end

或者使用等效的 Document.ready promise，这在与其他 promises 结合使用时非常有用：

Document.ready.then do |ready|
  alert "Page is ready to use!"
end

注意 Kernel#alert 方法的使用。

事件处理

使用 Element#on 方法可以将事件处理程序附加到元素：

Element.find('#header').on :click do
  puts "The header was clicked!"
end

可以为处理程序传递选择器作为第二个参数，以处理特定子元素的事件：

Element.find('#header').on(:click, '.foo') do
  puts "An element with a 'foo' class was clicked"
end

事件处理程序块可以可选地接收一个 Event 实例，该实例与 jQuery 事件进行 toll-free 桥接：

Element.find('#my_link').on(:click) do |evt|
  evt.stop_propagation
  puts "stopped the event!"
end

可以通过 #current_target 访问触发事件的元素：

Document.on :click do |evt|
  puts "clicked on: #{evt.current_target}"
end

CSS 样式和类名

Element 实例上可用的各种 jQuery 方法：

foo = Element.find('.foo')

foo.add_class 'blue'
foo.remove_class 'foo'
foo.toggle_class 'selected'

还有为 opal-jquery 添加的便利方法：

foo = Element.find('#header')

foo.class_name
# => 'red lorry'

foo.class_name = 'yellow house'

foo.class_name
# => 'yellow house'

Element#css 方法也用于获取/设置 CSS 样式：

el = Element.find('#container')
el.css 'color', 'blue'
el.css 'color'
# => 'blue'

3.2 HTTP/AJAX 请求

jQuery 的 Ajax 实现在顶层 HTTP 类中进行了封装。

HTTP.get("/users/1.json") do |response|
  puts response.body
  # => "{\"name\": \"Adam Beynon\"}"
end

传递给此方法的块用作请求成功和失败时的处理程序。要确定请求是否成功，请使用 ok? 方法：

HTTP.get("/users/2.json") do |response|
  if response.ok?
    alert "successful!"
  else
    alert "request failed :("
  end
end

也可以为每种情况使用不同的处理程序：

request = HTTP.get("/users/3.json")

request.callback {
  puts "Request worked!"
}

request.errback {
  puts "Request didn't work :("
}

请求实际上在 HTTP.get 方法内触发，但由于请求的异步性质，可以在请求返回之前随时添加回调和错误回调处理程序。

处理响应

Web 应用程序经常处理 JSON 响应，因此有一个实用的 #json 辅助方法来获取请求的 JSON 内容：

HTTP.get("/users.json") do |response|
  puts response.body
  puts response.json
end

# => "[{\"name\": \"Adam\"},{\"name\": \"Ben\"}]"
# => [{"name" => "Adam"}, {"name" => "Ben"}]

#body 方法始终返回原始响应字符串。

如果遇到错误，#status_code 方法将包含特定错误代码：

request = HTTP.get("/users/3.json")

request.callback { puts "it worked!" }

request.errback { |response|
  puts "failed with status #{response.status_code}"
}

提供一个 XHR 回调

要提供 XHR 回调，请包含带有 xhr 选项的 lambda：

update_progress = lambda do
  xhr = `new window.XMLHttpRequest()`
  update_progress = lambda do |evt|
    # 在这里更新您的进度
  end
  `xhr.upload.addEventListener("progress", update_progress, false)`
  xhr
end

cloud_xfer = HTTP.put "http://my.cloud.storage/location", xhr: update_progress, ... etc ...

3.3 使用 JQuery 插件

默认情况下，JQuery 使用的额外插件对 Ruby 代码不可用，您需要将这些函数 expose 给 opal-jquery。

Element.expose :cool_plugin

传递给 exposed 函数的参数将按原样传递，因此这些参数必须作为原生 JavaScript 而不是 Ruby 代码传递。可以使用 .to_n 方法将 Ruby 对象转换为原生 JavaScript 对象。

Element.expose :cool_plugin

el = Element['.html_element']
el.cool_plugin({argument: 'value', argument1: 1000}.to_n)

4. 项目安装方式

请参考本文档的“安装指南”部分。

---

以上就是 Opal jQuery 的技术文档，希望对您有所帮助。