Bootstrap Tags 项目技术文档

1. 安装指南

Bootstrap Tags 是一个基于 jQuery 的插件，用于扩展 Twitter Bootstrap 的标签功能。支持 Bootstrap 2.3.2 及以上版本。

安装方式

• 使用 Bower 进行安装：

  $ bower install bootstrap-tags
  

• 使用 Git 进行安装：

  $ git clone https://github.com/maxwells/bootstrap-tags.git
  

  其中，JavaScript 文件位于 dist/js 目录，CSS 文件位于 dist/css 目录。

2. 项目的使用说明

在项目中使用 Bootstrap Tags 插件，需要包含相应的 JavaScript 和 CSS 文件，并通过 jQuery 初始化标签功能。

使用示例

<!-- 引入 Bootstrap Tags 的 JS 和 CSS 文件 -->
<script src='path/to/bootstrap-tags/dist/js/bootstrap-tags.min.js'></script>
<link rel="stylesheet" type="text/css" href="path/to/bootstrap-tags/dist/css/bootstrap-tags.css" />

<div id="my-tag-list" class="tag-list"></div>
<script>
  $(function() {
    // 如果使用 Bootstrap 2，需要设置版本
    // Tags.bootstrapVersion = "2";
    $('#my-tag-list').tags({
      tagData: ["boilerplate", "tags"],
      suggestions: ["basic", "suggestions"],
      excludeList: ["not", "these", "words"]
    });
  });
</script>

3. 项目API使用文档

Bootstrap Tags 插件支持多种配置选项，以下是一些常用的 API 方法。

配置选项

以下选项可以通过 JavaScript 对象传递给 tags jQuery 函数：

$('selector').tags({
  readOnly: true,
  tagData: ["a", "prepopulated", "list", "of", "tags"],
  beforeAddingTag: function(tag){ console.log(tag); }
});

• bootstrapVersion: 指定生成的 HTML 应该使用哪个版本的 Bootstrap 格式。接受的值为 "2" 或 "3"。
• tagData: 初始化标签界面时使用的标签列表。
• tagSize: 描述要使用的输入大小。接受的值为 "lg"、"md" 或 "sm"。
• readOnly: 是否禁用用户输入。
• suggestions: 用户输入第一个字符时将自动填充的术语列表。
• suggestOnClick: 是否在点击时触发自动建议功能。
• caseInsensitive: 自动建议是否忽略大小写。
• restrictTo: 允许的标签列表（如果提供，将结合建议使用）。不在该列表中的用户输入标签将被忽略。
• exclude: 不允许的标签列表，支持通配符。
• popoverData: 每个标签的弹出数据列表。
• popovers: 是否在鼠标悬停时启用 Bootstrap 弹出窗口。
• popoverTrigger: 弹出窗口的触发方式。
• tagClass: 标签 div 的类名，用于样式。
• promptText: 当没有标签且没有输入内容时显示的占位符字符串。
• maxNumTags: 允许的最大标签数（用户添加的）。如果设置了此值，当标签数量超过此值时，输入将被禁用。
• readOnlyEmptyMessage: 在只读模式下如果没有标签显示的文本。
• beforeAddingTag: 在添加标签之前执行的外部操作。返回 false 将阻止添加标签。
• afterAddingTag: 在添加标签后执行的外部操作。
• beforeDeletingTag: 在删除标签之前执行的外部操作。返回 false 将阻止删除标签。
• afterDeletingTag: 在删除标签后执行的外部操作。
• definePopover: 返回新添加标签的弹出内容的函数。
• excludes: 如果希望排除标签，则返回 true，否则允许。

链式函数

以下是一些可链式调用的函数，用于操作标签数据：

• hasTag(tag:string): 是否存在标签。
• getTags(): 当前界面中的标签列表。
• getTagsWithContent(): 包含 tag 和 content 属性的 JavaScript 对象列表。
• getTag(tag:string): 返回标签字符串。
• getTagWithContent(tag:string): 返回具有 tag 和 content 属性的对象（弹出内容）。
• addTag(tag:string): 添加标签。
• renameTag(tag:string, newTag:string): 重命名标签。
• removeLastTag(): 如果存在，则移除最后一个标签。
• removeTag(tag:string): 移除指定的标签。
• addTagWithContent(tag:string, popoverContent:string): 添加带有相关弹出内容的标签。
• setPopover(tag:string, popoverContent:string): 更新标签的关联弹出内容。

示例

var tags = $('#one').tags({
  suggestions: ["here", "are", "some", "suggestions"],
  popoverData: ["What a wonderful day", "to make some stuff", "up so that I", "can show it works"],
  tagData: ["tag a", "tag b", "tag c", "tag d"],
  excludeList: ["excuse", "my", "vulgarity"],
});
tags.addTag("tag e!!").removeTag("tag b").setPopover("tag c", "Changed popover content");
console.log(tags.getTags());

4. 项目安装方式

请参考“安装指南”部分，使用 Bower 或 Git 进行安装。