xj.ripple

基本介绍

简介 : 这是一个无依赖，独立且开源的，前端点击波纹效果插件，它开箱即用(引入插件后为标签设置 xj-ripple 类名即可)，且参数丰富(30+ 参数涵盖了各种细节设置)，由于它采用了委托绑定的形式，所以通过配置，甚至能不需要设置类名就自动响应，如果你已经厌倦了乏味的点击效果，不妨为你的项目增加一些波纹吧，让交互变得更加有趣一些，顺便还能省去编写 :active{} 伪类样式的麻烦。

兼容 : IE10+ / Edge12+ / Firefox / Chrome / Safari / Opera / IOS Webkit / Android Platform

更新 : https://github.com/xjZone/xj.ripple/blob/master/upgrade.md

源码 : https://github.com/xjZone/xj.ripple/

协议 : Apache License 2.0

版本 :

引入插件

首先是引入相关的文件，推荐使用带 immutable 的 JSDelivr CDN：

如何使用

引入插件之后，在目标节点上添加 xj-ripple 类名，那么这个节点在被点击的时候就会自动响应波纹了，下面是一个简单的例子，为了展示波纹的效果，所以这里设置了一个 .box 类名来定义容器的样式，在后面的其他例子中，我们也会用这个 .box 来充当示范的容器，但其实它并没有什么特别之处，为了代码的简洁性，所以在之后的案例中我们就不再展示 .box 的样式代码了，大家了解即可。

四种模式

插件提供了四个类名，用于实现不同模式的波纹，xj-ripple 禁止波纹溢出，xj-ripple-out 允许波纹溢出，xj-ripple-mid 禁止波纹溢出且波纹将自动居中，xj-ripple-out-mid 允许波纹溢出且波纹将自动居中，下面是一个简单的例子，展示了四种模式的波纹效果，需要注意的是，溢出的波纹可能会导致父容器生成临时的滚动条，除非你能精确的控制尺寸，否则溢出模式的波纹一般只用于测试。

参数设置

插件提供了非常丰富的参数，用于定义波纹的各种细节，无论是圆角或颜色，亦或是尺寸或定位，皆可自由掌控，而这些参数都可通过使用目标容器上的 xj-ripple="{}" 这个内联属性来完成设置，下面是一个简单的例子，使用 radius 参数可修改波纹圆角(默认值是 50%)，使用 color 参数可修改波纹颜色(默认值是 currentColor)，如果你想了解更多的参数，可查阅文档后面的 # 参数列表。

测试状态

默认情况下，当波纹的 opacity 动画执行完毕，波纹节点就会被自动移除掉，这样可以节约浏览器资源，但立即移除节点也导致了我们很难在 DevTool 面板中检查并调试它，所以插件提供了 debug 参数，当这个参数被设为 true 时，波纹就不会被自动移除了，伴随波纹节点的还有节点 xj-ripple-temporary，它用于确定点击位置和容器左上角的距离，更多细节可查阅后面的 # 项目备注 - 02。

尺寸控制

在默认的情况下，波纹尺寸总是刚好能覆盖到容器的四个边角（包括 padding 不含 border），但你也可以使用插件提供的 width / height, minWidth / minHeight, maxWidth / maxHeight, extraWidth / extraHeight 这些参数来进一步调整波纹的尺寸，这些参数既可以使用绝对的 px 单位，也可以使用相对的 % 单位（基于波纹所在容器），下面是使用这些参数的简单案例。

圆心定位

在默认的情况下，波纹圆心要么是在点击的位置，要么是在容器的水平居中和垂直居中的交汇点，这取决于你使用的 xj-ripple 类名后面是否有带 -mid，但你也可以使用插件提供的 left / top 和 offsetLeft / offsetTop 这四个参数，来进一步调整波纹位置，这些参数既可以使用绝对的 px 单位，也可以使用相对的 % 单位（基于波纹所在容器），下面是使用这些参数的简单案例。

参数继承

内联属性 xj-ripple="{}" 不是非得设置在响应波纹的那个节点上，其实设置在目标节点的上层节点也是可以的，只要 inherit 参数不明文设为 false，那么这个内联属性的设置就可以被继承，正如下面的例子中所展示的那样，当目标节点和它的上层节点设置了同个属性时，层级越低的属性权重就越高，继承的好处是如果想定义某个区域的波纹，不需要逐个设置，只需要设置父容器然后继承就行。

禁止响应

当节点有 disabled 属性或 xj-ripple-disabled 类名或 cursor:not-allowed 样式时，节点被点击将不响应波纹，当节点的上层节点存在这些设置时，节点被点击也不响应波纹，但如果 forbid 参数被设置为 false，则子节点不受上层节点的影响，唯一例外是 cursor:not-allowed 样式，因为子节点会自动继承上层节点的指针样式，所以即使设置 forbid:false，子节点依旧是不响应波纹。

<p>
	
	<span class="box xj-ripple" disabled="disabled">            不响应波纹</span>
	<span class="box xj-ripple xj-ripple-disabled">             不响应波纹</span>
	<span class="box xj-ripple" style="cursor:not-allowed;">    不响应波纹</span>
</p>

<p>
	
	<div style="display:inline-block;vertical-align:top;" disabled="disabled">        <span class="box xj-ripple">不响应波纹</span></div>
	<div style="display:inline-block;vertical-align:top;" class="xj-ripple-disabled"> <span class="box xj-ripple">不响应波纹</span></div>
	<div style="display:inline-block;vertical-align:top;cursor:not-allowed;">         <span class="box xj-ripple">不响应波纹</span></div>
</p>

<p>
	
	<span style="display:inline-block;vertical-align:top;" disabled="disabled">       <span class="box xj-ripple" xj-ripple="{forbid:false}">                     会响应波纹</span></span>
	<span style="display:inline-block;vertical-align:top;" class="xj-ripple-disabled"><span class="box xj-ripple" xj-ripple="{forbid:false}">                     会响应波纹</span></span>
	<span style="display:inline-block;vertical-align:top;cursor:not-allowed;">        <span class="box xj-ripple" xj-ripple="{forbid:false}" style="cursor:auto;">会响应波纹</span></span>
</p>

使用背景

波纹不是非得使用纯色的，插件提供了 bg 参数，可以用于设置波纹的 background 样式，也就是说我们可以为波纹添加背景图，甚至是可以使用线性渐变或径向渐变来作为波纹的背景色，这样一来可套用一句老话：“限制住你的就只有你的想象力…”，如果你不习惯在 background 样式中设置所有的属性，当然也可以使用插件提供的 styleObject 参数，以 CSS 对象的形式来进行各种样式的设置。

修改目标

可用 insertTarget 参数定义波纹生成的位置，该参数默认值为 'auto'，也就是在点击的节点生成波纹，可以接受选择器或函数作为值让波纹在其他位置生成，在没设置 left / top 参数或 offsetLeft / offsetTop 参数时，波纹将定位于容器中心，波纹参数只会在触发点击的那个节点上获取，与目标容器没关系，目标容器需要做的是设置 position 不为 static 确保波纹能顺利定位。

<div style="display:inline-block;vertical-align:top;">
	<span class="box xj-ripple" xj-ripple="{insertTarget: ':self i'}">
		点击这里<br /><i class="box" style="position:relative;">波纹会在<br />这里响应</i>
	</span>
</div>

<div style="display:inline-block;vertical-align:top;">
	<span class="box xj-ripple" xj-ripple="{insertTarget: ':parent i'}">
		点击这里<br /><i class="box" style="position:relative;">波纹会在<br />这里响应</i>
	</span>
</div>

<div style="display:inline-block;vertical-align:top;">
	<span class="box xj-ripple" xj-ripple="{insertTarget: '#insertTag i'}" id="insertTag">
		点击这里<br /><i class="box" style="position:relative;">波纹会在<br />这里响应</i>
	</span>
</div>

<div style="display:inline-block;vertical-align:top;">
	<span class="box xj-ripple" xj-ripple="{insertTarget: 
	function(target){ return(target.querySelector('i')) }}">
		点击这里<br /><i class="box" style="position:relative;">波纹会在<br />这里响应</i>
	</span>
</div>

通过配置实现自动响应

如果你觉得手动添加 xj-ripple 类名还是太麻烦了点，那么或许可以考虑通过全局配置的 defaultSelector 参数，将目标节点的选择器追加到这个参数里，这样就能实现点击自动响应波纹了，甚至 HTML 结构都不需要改动，配置完成后你唯一需要做的，就只是为标签设置 position:relative; 和 overflow:hidden;，这是为了波纹能在标签中进行绝对定位且不要溢出，下面是个全局配置的例子。

通过预设定义动画细节

如果你对动画细节不满意，例如觉得波纹过于缓慢，那么可通过参数预设来对所有波纹的动画进行重定义，插件提供了 transitionProperty, transitionDuration, transitionTimingFunction, transitionDelay 共四个参数用于控制动画的细节，你当然也可以在内联属性 xj-ripple="{}" 上使用这些属性，但如果逐个设置未免太没效率了，此时依靠参数预设来让全局的波纹都生效会更加方便。

单标签响应波纹

单标签元素如 input 或 img，由于它们并不支持子标签，所以无法在这类标签中实现波纹效果，另外就是 select 和 video 等特殊标签也不支持普通元素作为它们的子标签，所以这些标签也无法实现波纹，但是如果你非要实现，也可以将这类标签嵌在一个双标签之中来处理，例如说把标签放在一个 div 中，然后将类名添加在这个 div 上，例如下例中第二个 input 就被嵌套在 div 中。

使用预设的类名

你可以通过使用预设的类名，来更加方便的设置波纹样式，插件默认提供了 .xj-ripple-primary, .xj-ripple-success, .xj-ripple-warning, .xj-ripple-danger, .xj-ripple-extra, .xj-ripple-info, .xj-ripple-black, .xj-ripple-white 总共八个类名，用于定义不同颜色或者说状态的波纹，你当然也可以通过相同的写法，来预设更多的类名，下面是关于类名预设的一个简单案例。

xj.ripple 对象

全局中的 xj.ripple 对象上只有一个属性和一个方法，xj.ripple.version 属性会返回当前插件的版本，xj.ripple.create() 方法则是用于手动创建波纹，该方法接受两个参数，第一个参数是生成波纹的容器(必填)，第二个参数是设置波纹的参数对象(可选)，下面是一个使用该方法的例子，点击左侧容器可在右侧容器中生成一个波纹，当方法的参数与容器的参数重复时，方法的参数优先级会更高。

配置列表

以下 Demo 罗列了本插件所有可用的配置，并且展示了插件进行全局配置的具体操作方法，需要注意的是，全局配置得在引入插件之前就设置好，否则插件加载并执行的时候找不到配置，就会认为配置不存在，并且版本号也要对得上，否则插件也是不理会的，例如本页面使用的插件是 0.5.0 的版本，在 xj.rippleConfig 对象后面跟着的就是 ['0.5.0']，版本匹配是考虑到插件多版本并存而设计的。

参数列表

以下 Demo 罗列了本插件所有可用的参数，并且展示了插件进行参数预设的具体操作方法，需要注意的是，参数预设得在引入插件之前就设置好，否则插件加载并执行的时候找不到预设，就会认为预设不存在，并且版本号也要对得上，否则插件也是不理会的，例如本页面使用的插件是 0.5.0 的版本，在 xj.rippleOption 对象后面跟着的就是 ['0.5.0']，版本匹配是考虑到插件多版本并存而设计的。

项目备注

01. 在 V0.2.X 和 V0.3.X 时，插件是使用了 box-shadow 样式生成波纹，由于 box-shadow 并不会实际占据空间，所以即使波纹溢出了，也不会导致波纹所在容器出现滚动条，但是 Chrome 从 V101 开始修改了 box-shadow 的圆角算法，导致大于容器那部分的阴影再也无法保持纯圆状态，所以不得已 XJ 只好在 V0.4.X 又走回了 V0.1.X 的老路，也就是使用标签的 width & height 样式来生成波纹，使用 width & height 来实现波纹的尺寸，可为标签实现背景图和渐变色等效果，但缺点就是波纹溢出时可能会生成滚动条。

02. 当开启 debug 模式时，你会发现目标容器在生成波纹节点的同时，还会出现一个 xj-ripple-temporary 节点，这个节点用于确定点击位置和目标容器左上角那个点的距离，之所以要用一个临时节点来计算距离，是因为其他手段如 DomRect.left & DomRect.top 或 event.offsetX & event.offsetY，它们都没考虑到滚动条在左侧时的情况，结果可能存在偏差，只能用临时节点来解决这个问题。

03. SVG 标签无法接受普通标签作为子节点，所以也就没法实现波纹效果，XJ 当然也想过在 SVG 中改用 circle 标签来实现波纹，但 SVG 标签的样式和操作等细节跟 HTML 标签还是有些区别，不是简单的替换就能解决的，所以这个需求只能是未来再考虑要不要实现了。

04. 有疑问或者发现 BUG，可到 GitHub 提 Issue，如果觉得插件写得还行，在 GitHub 中为本项目点个 ★Star 吧，感谢啦 ಠ‿ಠ ❤。

xj.ripple 点击波纹特效