README

jSignature 是一个 jQuery 插件，简化了在浏览器窗口中创建签名捕获字段的过程，允许用户使用鼠标、笔或手指绘制签名。

jSignature 将签名捕获为笔触的矢量轮廓。虽然 jSignature 也可以导出高质量的位图（PNG），但提取签名的高可伸缩性笔触运动坐标（即矢量图像）允许签名渲染具有更大的灵活性。

通过平滑和压力模拟，我们额外努力使笔触在签名者在屏幕上绘制时看起来更美观。

所有主要的桌面、平板和手机浏览器都得到支持。默认使用 HTML5 Canvas 元素。当浏览器不支持实际的 Canvas 时（如 Internet Explorer v.8 及以下版本），我们会回退到基于 Flash 的 Canvas 元素模拟器（FlashCanvas）。

jSignature 仅实时渲染捕获数据的设备适当的“最漂亮”的近似值。捕获的数据始终相同——我们尽可能捕获尽可能多的运动坐标。笔触的渲染根据浏览器的功能、设备的效率和屏幕大小而有所不同。

有意对捕获签名的屏幕表示进行降级和增强，以确保渲染不会影响捕获的响应性。例如，在渲染速度较慢的设备（如 Android 浏览器、基于 FlashCanvas 的 Canvas 模拟）上，平滑度会提高一个等级，以补偿捕获笔触坐标中的大差距——这是捕获设备效率低下的结果。在所有情况下，客户都应满意于绘画的响应性和美观。

jSignature 使其轻松地集成到现有的样式网站中。jSignature 自动检测包装元素上使用的颜色（文字颜色=笔颜色，背景=背景）并自动选择一个令人愉悦的中色调用于“装饰”（签名线）。jSignature 适应固定和可变宽度网页设计以及各种大小的屏幕（手机、平板、计算机屏幕），并在父元素更改大小时自动调整绘图区域和签名。

请参阅此处演示。

将 jSignature 添加到您的页面

查看源代码树中的 libs 文件夹。从中选择 3 个文件

1. jSignature.min*.js（'*' 表示您有选择。您可以选择基于 jQuery 的常规构建或特殊的 jQuery.NoConflict 构建。）

2. flashcanvas.js

3. flashcanvas.swf

jSignature 依赖于（更或更近期的）jQuery

如果您不打算支持 IE 7 和 8，则不需要下载 FlashCanvas 文件。

请注意，FlashCanvas 是一个包含两个文件的统一组，即 flashcanvas.swf 和 flashcanvas.js，这两个文件都必须位于同一个文件夹中。不要从不同的文件夹托管它们，因为 flashcanvas.js 会从它被提供的同一个文件夹中查找 flashcanvas.swf。不要将 flashcanvas.js 重命名为任何其他名称，因为它通过那个名称在 DOM 中查找自己以确定从哪里加载 flashcanvas.swf。

jSignature 本身有三个不同的代码片段被整合到一个压缩可部署文件中

1. 准备 Canvas 元素的代码。它包括检测浏览器功能、在 div 的限制内最大化 canvas、在需要时设置使用 Flashcanvas 的模拟 Canvas。
2. 处理实际签名捕获 + 数据导入/导出 API 的代码。它附加并监听运动事件处理程序，在数据结构中存储笔触数据，处理 API 调用。
3. 插件可以帮助您以方便的格式获取签名数据，例如原始数据坐标、图像、压缩的URL兼容字符串、SVG。

如果您确信您的受众将限于特定的浏览器引擎（您通过嵌入浏览器小部件部署，使用类似PhoneGap的东西），您可以卷起袖子，拔出第1部分。如果您知道您只需要一个导出/导入插件，请从最小化可部署文件中移除您不需要的插件。

更多自定义数据导出/导入插件可以单独加载，而无需重新最小化主要可部署文件。但是，最小化既有趣又简单。只需查看wscript.py文件，修改几行以包括/排除某些部分。

对于“通用”部署场景（包括对旧IE的支持）将以下内容添加到您的页面中

<!-- this, preferably, goes inside head element: -->
<!--[if lt IE 9]>
<script type="text/javascript" src="path/to/flashcanvas.js"></script>
<![endif]-->

<div id="signature"></div>

<!-- you load jquery somewhere before jSignature ... -->
<script src="path/to/jSignature.min.js"></script>
<script>
    $(document).ready(function() {
        $("#signature").jSignature()
    })
</script>

解释

• [if lt IE 9]部分为小于9的IE加载Flashcanvas库。（Flashcanvas仅在IE上受支持，所以，进行特性检测是没有意义的。）
• 我们标记一个div，其中将在其中创建canvas元素。任何ID或其他jQuery选择器都行。
• 我们加载jSignature插件。
• 最后，脚本在指定的DIV内调用签名小部件。

API

以下方法在jQuery对象之上暴露：.jSignature(String command, *args)

参数因command而异。当提供时，command预期是一个字符串，其中包含jSignature的命令。目前支持以下命令

• init是默认操作。init接受一个参数 - 设置对象。您可以在初始化时省略命令，只需传递设置对象即可。以传统的jQuery链式方式返回应用于元素的jQuery对象引用。
• reset只是清除签名板、数据存储（并将签名线和其他装饰物放回）。以传统的jQuery链式方式返回应用于元素的jQuery对象引用。
• clear是reset的别名，用于遗留目的。
• destroy销毁实例。
• getData接受一个参数 - 数据格式的名称。返回适用于该数据格式的数据对象。
• setData接受两个参数 - 数据对象，数据格式名称。当数据对象是数据-url模式的字符串时，您不需要指定数据格式名称。数据格式名称（MIME）将从数据-url前缀中隐含。下面有示例。以传统的jQuery链式方式返回应用于元素的jQuery对象引用。
• importData是setData的别名，用于遗留目的。
• listPlugins接受一个参数 - 表示插件分类（目前只支持export、import）的字符串。返回一个字符串数组。
• disable使canvas只读并禁用jSignature按钮。
• enable使canvas只读并启用jSignature按钮。
• isModified返回一个布尔值，如果jSignature被修改则返回true，否则返回false。
• getSettings返回jSignature实例的可配置设置。
• updateSetting接受三个参数 - 设置名称、新值、布尔值，如果更改应影响当前签名或未来的笔画。这允许您更新某些设置，如lineWidth或line颜色，并且通过第三个参数，您可以使更改应用于现有的笔画。目前，仅对颜色等少数设置更新现有笔画的更改有效。返回更新后的值。

使用示例

var $sigdiv = $("#signature")
$sigdiv.jSignature() // inits the jSignature widget.
// after some doodling...
$sigdiv.jSignature("reset") // clears the canvas and rerenders the decor on it.

// Getting signature as SVG and rendering the SVG within the browser. 
// (!!! inline SVG rendering from IMG element does not work in all browsers !!!)
// this export plugin returns an array of [mimetype, base64-encoded string of SVG of the signature strokes]
var datapair = $sigdiv.jSignature("getData", "svgbase64") 
var i = new Image()
i.src = "data:" + datapair[0] + "," + datapair[1] 
$(i).appendTo($("#someelement")) // append the image (SVG) to DOM.

// Getting signature as "base30" data pair
// array of [mimetype, string of jSignature's custom Base30-compressed format]
datapair = $sigdiv.jSignature("getData","base30") 
// reimporting the data into jSignature.
// import plugins understand data-url-formatted strings like "data:mime;encoding,data"
$sigdiv.jSignature("setData", "data:" + datapair.join(",")) 

请参阅测试和index.html以获取更多示例。

数据导入/导出（和插件）

以下插件（数据格式）是jSignature主线最小化可分发的一部分

• 默认（仅导出）(位图) 数据格式与早期版本中在未传递参数的情况下调用 getData 产生的 jSignature 输出格式兼容。"默认" 现在在您调用 $obj.jSignature("getData") 时（显然）默认触发。数据格式是 Canvas 原生生成的 - 数据-url 格式、base64 编码（可能是 PNG）的位图数据，如下所示：data:image/png;base64,i1234lkj123;k4;l1j34l1kj3j... 此导出调用返回一个单独的数据-url 格式字符串。
• native（导出和导入）(矢量) 数据格式是绘制笔触作为具有 .x 和 .y 属性的对象数组的自定义表示。这个 JavaScript 对象结构是 jSignature 中存储每个绘制笔触的实际数据结构。该结构专门设计用于 收集 笔迹数据点的速度和效率。虽然这种结构看起来有点反直觉，像章鱼一样，但它（a）允许快速堆积二维坐标，无需为每个数据点创建 Point 对象，并且（b）便于通过循环处理数据。虽然您可以将其 JSON 化，传递它，解析它，从它渲染，但这可能不是存储数据的最有效方式，因为 jSignature 的其他主要版本中内部格式可能会改变。我建议查看 base30 格式，它是 "native" 作为 JSON 的直接但紧凑的等效格式。这种数据适用于运行统计信息（签名在画布上的大小、位置）和编辑笔触（例如允许“撤销最后一步”）。
• base30（别名 image/jSignature;base30）（导出和导入）(矢量) 数据格式是一种基于 Base64 的压缩格式，旨在实现荒谬的紧凑性和原生 URL 兼容性。它是将所有矢量压缩到紧凑字符串表示的 "native" 数据结构。"extras" 文件夹中提供了将此格式解压缩为可渲染格式（如 SVG、语言原生坐标数组）的代码示例。将数据传递到服务器的一种可能方式是 JSONP，它有一个实际的 URL 长度限制（当然是由 IE 强制实施的）不超过 2000+ 个字符。此压缩格式与原生 URL 兼容，无需重新编码，但对于大多数非复杂签名，它可以适应 2000 个字符。
• svg（别名 image/svg+xml）（仅导出）(矢量) 数据格式将签名生成 SVG 图像（SVG XML 文本）。所有笔触都进行了去噪和平滑处理。这种格式是“易于查看”和“高度可缩放”之间的良好媒介。SVG 在今天的大多数浏览器中都有原生支持，并且，尽管如此，这种格式可以无限缩放和增强以供打印。数据是文本形式，便于存储和传输。调用 jSignature("getData","svg") 返回一个形式为 ["image/svg+xml","svg xml here"] 的数组。
• svgbase64（别名 image/svg+xml;base64）（仅导出）(矢量) 这与 "svg" 插件相同，但 SVG XML 文本是使用 base64 编码压缩的。尽管许多浏览器现在都有内置的 base64 编码器（ btoa() ），但一些，如 Internet Explorer，则没有。此插件有自己的（短而高效的）基于软件的 base64 编码器副本，它在缺少 btoa() 的浏览器上调用。调用 jSignature("getData","svgbase64") 返回一个形式为 ["image/svg+xml;base64","base64-encoded svg xml here"] 的数组。这个由两个成员组成的数组很容易转换为数据-url 格式字符串（"data:" + data.join(",")）或转换为参数传递给服务器作为表单值。
• image（仅导出）(位图) 数据格式基本上与上面的 "default" 相同，但它被解析成与 "svg" 导出类似的结构中的独立对象。示例（缩短）["image/png;base64","i123i412i341jijalsdfjijl234123i..."]。因为图像导出过滤器依赖于（有些不可靠的）浏览器支持并拾取不必要的数据，建议仅用于演示和开发期间。

选择导出/存储格式。

我知道您很想从jSignature获取“图像”，但请控制自己，远离它。相反，考虑捕获“base30”或“svg”数据，并在后期制作中服务器端进行增强和渲染。

如果您导出“位图”，图像将保留实际的绘图颜色、大小、缺陷，并且最重要的是，可能无法在所有浏览器上工作。

• 装饰（签名行）将在图像上。如果jSignature使用深色背景和浅色笔色进行了样式设计，那么您在图像上就会得到相同的效果——深色背景，浅色覆盖灰色签名行的绘制。这张图像几乎无法用于打印。如果您的背景与笔的强度相同（例如，红色在蓝色上），那么当打印成黑白时，图像将变成一个深灰色矩形。如果您更改页面颜色，捕获的图像现在开始呈现出那些颜色。
• Android 1.6 - 2.2（2.3？）不支持canvas.getDataURL方法，这是bitmap导出功能的核心。
• 小屏幕（手机）会产生微小的、难看的位图。
• 与矢量图相比，canvas导出的位图大小巨大，因为它保留了所有中间色调和背景像素。

如果您想强迫自己永远只使用黑白签名捕获网页样式，请使用位图导出。如果您想因为备份包含所有位图数据的数据库需要超过一天而让您的数据库管理员大声疾呼，请使用位图导出。如果您想因为您的签名捕获格式无法轻松集成到他们新精心设计的、炫酷的产品/服务而让您的销售/业务部门大声疾呼，请使用位图导出。如果您想解释为什么您选择的签名格式导出无法在所有目标平台上工作，请使用位图导出。如果您想走捷径，现在让被解雇后的IT人员处理您收集的大量彩色像素的复杂任务，请使用位图导出格式。

如果捕获的签名与“业务”、“打印”或“多个展示场所”有关，请使用矢量格式，如“base30”或“svg”数据，并在后期制作中进行增强和渲染。解压缩和基本的渲染代码（截至2012年2月的.NET、PHP）可以在“extras”文件夹中找到。您将使用这些作为提供循环坐标数据数组的核心，用于您自己的渲染逻辑。

事件

jSignature初始化的DOM元素在将笔画添加到存储后立即发出‘change’事件。（换句话说，当用户完成每根笔的绘制时。如果用户绘制3根笔，此事件将发出3次，每次绘制完毕后。）

以下是绑定该事件的方法

$("#signature").bind('change', function(e){ /* 'e.target' will refer to div with "#signature" */ })

事件通过“线程”（setTimeout(..., 3)）异步发出，因此您不需要将事件处理器包裹在任何类型的“线程”中，因为jSignature小部件将继续运行，并等待您完成自定义事件处理器逻辑。

许可，版权

MIT许可

请参阅源代码标题以获取完整和最新的版权归属。