jQCloud 技术文档

2024-12-24 09:20:22作者：龚格成

1. 安装指南

jQCloud 是一个基于 jQuery 的插件，用于生成美观且纯 HTML + CSS 的词云和标签云。以下是安装 jQCloud 的步骤：

确保项目中已引入 jQuery。
下载 jQCloud 文件。将 jqcloud-1.0.4.js（或其压缩版 jqcloud-1.0.4.min.js）和 jqcloud.css 放置在项目中的某个位置，并在 HTML 代码中引入它们。

对于使用 Ruby on Rails 的用户，可以使用 jqcloud-rails gem。

2. 使用说明

使用 jQCloud 非常简单。首先，选择一个容器元素，并使用 jQuery 调用 jQCloud(wordsArray) 方法。

以下是一个详细的示例：

<!DOCTYPE html>
<html>
  <head>
    <title>jQCloud 示例</title>
    <link rel="stylesheet" type="text/css" href="jqcloud.css" />
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>
    <script type="text/javascript" src="jqcloud-1.0.4.js"></script>
    <script type="text/javascript">
      $(function() {
        var word_array = [
          {text: "Lorem", weight: 15},
          {text: "Ipsum", weight: 9, link: "http://jquery.com/"},
          {text: "Dolor", weight: 6, html: {title: "我可以有 HTML 属性"}},
          {text: "Sit", weight: 7},
          {text: "Amet", weight: 5}
          // ...你可以添加更多单词
        ];

        $("#example").jQCloud(word_array);
      });
    </script>
  </head>
  <body>
    <div id="example" style="width: 550px; height: 350px;"></div>
  </body>
</html>

请注意，容器元素在调用 jQCloud 方法时必须可见且具有非零尺寸。

3. 项目 API 使用文档

以下是 jQCloud 的 API 文档。

单词选项

每个单词对象需要指定以下必填属性：

text (字符串)：单词文本。
weight (数字)：表示单词相对重要性的数字（如出现次数等）。值的范围是任意的，它们将被线性映射到 1 到 10 的离散刻度。

此外，还可以为每个单词指定以下可选选项：

html (对象)：指定要设置在单词上的 HTML 属性的对象（例如：{class: "customclass", title: "一个标题"}）。可以设置任何属性，除了 "id"，因为 jQCloud 会设置它。
link (字符串或对象)：如果指定，单词将被包装在 HTML 链接 (<a> 标签) 中。如果 link 是字符串，它应是被链接的 URL，并用作链接的 href 属性。如果 link 是对象，可以指定 <a> 标签的 HTML 属性，如 {href: "http://myurl.com", title: "一个链接"}。
afterWordRender (函数)：单词渲染完成后调用的函数。在函数中，this 指向包含单词的 <span> 元素。
handlers (对象)：指定要绑定到单词的事件处理器的对象（例如：{click: function() { alert("它起作用了！"); } }）。

云选项

jQCloud 接受一个包含整个云配置的对象作为第二个参数：

$("#example").jQCloud(word_list, {
  width: 300,
  height: 200
});

所有云范围的配置都是可选的，可用的完整选项列表如下：

width (数字)：词云容器元素的宽度。默认为原始宽度。
height (数字)：词云容器元素的高度。默认为原始高度。
center (对象)：词云中心的 x 和 y 坐标，相对于容器元素（例如：{x: 300, y: 150}）。默认为容器元素的中心。
afterCloudRender (函数)：整个云渲染完成后调用的回调函数。
delayedMode (布尔值)：如果为 true，单词将一个接一个地渲染，每个单词之间有微小延迟。这可以防止在渲染大量单词时浏览器冻结。如果为 false，云将一次性渲染。默认为 true，如果单词数量超过 50。
shape (字符串)：云的形状。默认为椭圆形，但可以设置为 "rectangular" 以绘制矩形形状的云。
removeOverflowing (布尔值)：如果为 true，会移除溢出容器的单词。默认为 true。