JS组件
<h1>JS组件</h1>
<p><code>Dcat Admin</code>内置了一些常用的JS功能组件，通过全局变量<code>Dcat</code>可以访问到这些功能方法。</p>
<h2>监听JS脚本加载完毕事件 (ready)</h2>
<p>通过<code>Dcat.ready</code>方法设置的回调函数会在所有的<code>JS</code>脚本都加载完毕后执行。</p>
<p>> {tip} 只有在模板文件中写<code>JS</code>代码才需要使用<code>Dcat.ready</code>，当在<code>php</code>代码中使用<code>Dcat\Admin\Admin::script</code>方法添加<code>JS</code>代码时是不需要使用<code>Dcat.ready</code>方法的。因为在构建页面的时候系统会自动把代码放在<code>Dcat.ready</code>事件内执行。</p>
<pre><code class="language-html">&lt;div&gt;...&lt;/div&gt;
&lt;script&gt;
Dcat.ready(function () {
// 写你的逻辑
console.log('所有JS脚本都加载完了');
});
&lt;/script&gt;</code></pre>
<p><a name="init"></a></p>
<h2>动态监听元素生成 (init)</h2>
<p>通过<code>Dcat.init</code>可以监听动态生成的页面元素并设置一个回调，下面来举一个简单的例子来演示用法：</p>
<p>假如一个元素是<code>JS</code>动态生成的，如果我们需要对这个元素绑定一个点击事件的话，那么我们通常需要这么做</p>
<pre><code class="language-html">&lt;div class=&quot;selector&quot;&gt;test&lt;/div&gt;
&lt;script&gt;
Dcat.ready(function () {
// 需要先 off 再 on 否则页面刷新后会造成重复绑定问题
$(document).off('click', '.selector').on('click', '.selector', function () {
...
})
});
&lt;/script&gt;</code></pre>
<p>上面这种做法一来比较麻烦，需要先<code>off</code>再<code>on</code>；二来无法对动态生成的元素做一些特殊处理，例如你想在<code>.selector</code>生成后改变背景颜色，这个操作就没办法做到。</p>
<p>在<code>Dcat Admin</code>中我们可以使用<code>Dcat.init</code>方法来监听元素动态生成，可以很方便的解决上面两个问题</p>
<pre><code class="language-html">&lt;div class=&quot;selector&quot;&gt;test&lt;/div&gt;
&lt;script&gt;
Dcat.ready(function () {
// $this 是当前元素的jquery dom对象
// id 是当前元素的id属性，如果当前元素没有id则会自动生成一个随机id
Dcat.init('.selector', function ($this, id) {
// 修改元素的背景色
$this.css({background: &quot;#fff&quot;});
// 这里不需要 off 再重新 on，因为这个匿名函数只会执行一次
$this.on('click', function () {
...
});
});
});
&lt;/script&gt;</code></pre>
<p><code>Dcat.init</code> 接受两个参数</p>
<ol>
<li><code>selector</code> 需要监听的元素的<code>css选择器</code></li>
<li><code>callback</code> 事件回调，当元素生成时触发，且只触发一次</li>
</ol>
<p>其中<code>callback</code>回调接收两个参数如下</p>
<ul>
<li><code>$this</code> 是当前元素的jquery dom对象</li>
<li><code>id</code> 是当前元素的id属性，如果当前元素没有id则会自动生成一个随机id</li>
</ul>
<h2>手动触发JS脚本加载完毕事件</h2>
<p>通过<code>Dcat.triggerReady</code>方法可以手动触发<code>JS</code>脚本加载完毕事件，这就意味着会自动执行在此之前所有通过<code>Dcat.ready</code>方法设置的回调函数。</p>
<p>> {tip} 这个功能普通开发很少会用到，只有一些比较深度的组件定制会用到，比如<a href="model-form-modal.md">表单弹窗</a>功能就用到了此方法。</p>
<pre><code class="language-js">Dcat.triggerReady();</code></pre>
<h2>Pjax刷新页面</h2>
<p>通过<code>Dcat.reload</code>方法可以调用<code>Pjax.reload</code>方法实现页面刷新和跳转功能。</p>
<p>刷新当前页面</p>
<pre><code class="language-php">Admin::script(
&lt;&lt;&lt;JS
// 3秒后刷新当前页面
setTimeout(function () {
Dcat.reload();
}, 3000);
JS
);</code></pre>
<p>跳转页面</p>
<pre><code class="language-php">$url = admin_url('auth/users');
Admin::script(
&lt;&lt;&lt;JS
// 3秒后跳转到 admin/auth/users 页面
setTimeout(function () {
Dcat.reload('{$url}');
}, 3000);
JS
);</code></pre>
<h2>Toastr提示框</h2>
<p><code>Dcat Admin</code>集成了<a href="https://github.com/CodeSeven/toastr">Toastr</a>插件，下面是使用方法</p>
<h3>success</h3>
<pre><code class="language-js">Dcat.success('更新成功');
// 使用标题
Dcat.success('更新成功', '我是标题');
// 传递参数
Dcat.success('更新成功', null, {
timeOut: 5000, // 5秒后自动消失
});</code></pre>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/zmB4EPhS3u.png!large" alt="" /></p>
<h3>error</h3>
<pre><code class="language-js">Dcat.error('服务器出现未知错误');
// 使用标题
Dcat.error('服务器出现未知错误', '我是标题');
// 传递参数
Dcat.error('服务器出现未知错误', null, {
timeOut: 5000, // 5秒后自动消失
});</code></pre>
<h3>warning</h3>
<pre><code class="language-js">Dcat.warning('警告');
// 使用标题
Dcat.warning('警告', '我是标题');
// 传递参数
Dcat.warning('警告', null, {
timeOut: 5000, // 5秒后自动消失
});</code></pre>
<h3>info</h3>
<pre><code class="language-js">Dcat.info('提示信息');
// 使用标题
Dcat.info('提示信息', '我是标题');
// 传递参数
Dcat.info('提示信息', null, {
timeOut: 5000, // 5秒后自动消失
});</code></pre>
<p>更多用法请参考<a href="https://github.com/CodeSeven/toastr">toastr官方文档</a></p>
<h2>sweetalert2弹窗</h2>
<p><code>Dcat Admin</code>集成了<a href="https://github.com/sweetalert2/sweetalert2">sweetalert2</a>插件，下面是使用方法</p>
<h3>confirm</h3>
<p>通过<code>Dcat.confirm</code>方法可以弹出确认弹窗，此方法接收5个参数</p>
<ul>
<li><code>title</code> <code>string</code> 确认信息标题</li>
<li><code>message</code> <code>string</code> 确认信息内容，此参数可以不传</li>
<li><code>success</code> <code>function</code> 点击确认按钮触发的回调函数</li>
<li><code>fail</code> <code>function</code> 点击取消按钮触发的回调函数，此参数可以不传</li>
<li><code>options</code> <code>object</code> 配置参数，可参考<a href="https://github.com/sweetalert2/sweetalert2">sweetalert2官方文档</a></li>
</ul>
<pre><code class="language-js">Dcat.confirm('确认要删除这行数据吗？', null, function () {
console.log('确认删除');
$.post(...);
});</code></pre>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/lp40C74OtV.png!large" alt="" /></p>
<h3>success</h3>
<pre><code class="language-js">Dcat.swal.success('标题');
Dcat.swal.success('标题', '内容');
Dcat.swal.success('标题', '内容', {
...
});</code></pre>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/OrhZ4dvA5R.png!large" alt="" /></p>
<h3>error</h3>
<pre><code class="language-js">Dcat.swal.error('标题');
Dcat.swal.error('标题', '内容');
Dcat.swal.error('标题', '内容', {
...
});</code></pre>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/lnp47PDecK.png!large" alt="" /></p>
<h3>warning</h3>
<pre><code class="language-js">Dcat.swal.warning('标题');
Dcat.swal.warning('标题', '内容');
Dcat.swal.warning('标题', '内容', {
...
});</code></pre>
<h3>info</h3>
<pre><code class="language-js">Dcat.swal.info('标题');
Dcat.swal.info('标题', '内容');
Dcat.swal.info('标题', '内容', {
...
});</code></pre>
<p>更多用法请参考<a href="https://github.com/sweetalert2/sweetalert2">sweetalert2官方文档</a></p>
<h2>layer弹出层</h2>
<p><code>Dcat Admin</code>集成了<a href="http://layer.layui.com/">layer弹出层</a>，用法请参考官方文档</p>
<pre><code class="language-js">layer.open({
...
})</code></pre>
<h2>Loading效果</h2>
<p><code>Dcat Admin</code>集成了三种常见的loading效果，<a href="http://103.39.211.179:8080/admin/components/loading">在线体验点我</a></p>
<h3>全屏</h3>
<p>通过<code>Dcat.loading</code>方法可以设置一个占满全屏幕的遮罩层，并在中间位置显示<code>loading</code>图标。</p>
<p>此方法接收一个<code>object</code>类型的参数：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>类型</th>
<th>默认值</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>zIndex</td>
<td><code>int</code></td>
<td>999991014</td>
<td>设置css的z-index(层重叠顺序)样式</td>
</tr>
<tr>
<td>width</td>
<td><code>string</code></td>
<td>58px</td>
<td>设置loading图标宽度</td>
</tr>
<tr>
<td>color</td>
<td><code>string</code></td>
<td>#bacad6</td>
<td>设置loading图标的颜色</td>
</tr>
<tr>
<td>background</td>
<td><code>string</code></td>
<td>transparent</td>
<td>设置遮罩层背景颜色</td>
</tr>
<tr>
<td>style</td>
<td><code>string</code></td>
<td></td>
<td>设置loading图标的css样式</td>
</tr>
</tbody>
</table>
<pre><code class="language-js">// 开启loading效果
Dcat.loading();
// 3秒后自动移除loading效果
setTimeout(function () {
Dcat.loading(false);
})</code></pre>
<p>效果</p>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/FIWAUFg1qn.png!large" alt="" /></p>
<p>更改loading图标的颜色</p>
<pre><code class="language-js">// 更改颜色
Dcat.loading({
color: Dcat.color.primary,
});</code></pre>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/WPIC4wwq5Q.png!large" alt="" /></p>
<h3>附着于指定元素</h3>
<p>通过<code>$.fn.loading</code>方法可以把loading效果附着于当前元素，此方法同样接收一个<code>object</code>类型参数：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>类型</th>
<th>默认值</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>zIndex</td>
<td><code>int</code></td>
<td>100</td>
<td>设置css的z-index(层重叠顺序)样式</td>
</tr>
<tr>
<td>width</td>
<td><code>string</code></td>
<td>52px</td>
<td>设置loading图标宽度</td>
</tr>
<tr>
<td>color</td>
<td><code>string</code></td>
<td>#bacad6</td>
<td>设置loading图标的颜色</td>
</tr>
<tr>
<td>background</td>
<td><code>string</code></td>
<td>#fff</td>
<td>设置遮罩层背景颜色</td>
</tr>
<tr>
<td>style</td>
<td><code>string</code></td>
<td></td>
<td>设置loading图标的css样式</td>
</tr>
</tbody>
</table>
<pre><code class="language-js">// 开启loading效果
$('#card').loading();
// 关闭loading效果
$('#card').loading(false);
// 更改loading图标颜色
$('#card').loading({
color: Dcat.color.primary,
});
// 更改遮罩层颜色
$('#card').loading({
background: '#f3f3f3',
});</code></pre>
<p>效果</p>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/ziHL5feEAV.png!large" alt="" /></p>
<h3>按钮</h3>
<pre><code class="language-js">// 开启loading效果
$('#submit-button').buttonLoading();
// 关闭loading效果
$('#submit-button').buttonLoading(false);</code></pre>
<p>效果
<img src="https://cdn.learnku.com/uploads/images/202004/26/38389/rNMFWAHPqJ.png!large" alt="" /></p>
<h3>a标签</h3>
<p>点击<code>a</code>标签同样支持loading效果</p>
<pre><code class="language-js">// 开启loading效果
$('a').buttonLoading();
// 关闭loading效果
$('a').buttonLoading(false);</code></pre>
<p>效果
<img src="https://cdn.learnku.com/uploads/images/202004/26/38389/IE8kGdupKW.png!large" alt="" /></p>
<h2>Ajax表单提交</h2>
<p><code>Dcat Admin</code>集成了<a href="https://github.com/jquery-form/form">jquery-form</a>组件用于实现<code>ajax</code>提交表单功能。</p>
<p>通过<code>Dcat.Form</code>方法可以当即发起<code>ajax</code>提交表单请求，此方法接受一个<code>object</code>类型参数：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>类型</th>
<th>默认值</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>form</td>
<td><code>string</code></td>
<td><code>object</code></td>
<td>表单的 jquery 对象或者css选择器</td>
</tr>
<tr>
<td>validate</td>
<td><code>bool</code></td>
<td><code>false</code></td>
<td>是否开启表单验证，可参考<a href="#validate">表单验证</a></td>
</tr>
<tr>
<td>errorClass</td>
<td><code>string</code></td>
<td>has-error</td>
<td>字段验证出错时添加的样式，一般使用默认值即可</td>
</tr>
<tr>
<td>errorContainerSelector</td>
<td><code>string</code></td>
<td>.with-errors</td>
<td>表单错误信息容器css选择器，一般使用默认值即可</td>
</tr>
<tr>
<td>groupSelector</td>
<td><code>string</code></td>
<td>.form-group,.form-label-group,.form-field</td>
<td>表单组css选择器，一般使用默认值即可</td>
</tr>
<tr>
<td>errorTemplate</td>
<td><code>string</code></td>
<td></td>
<td>错误信息模板，使用默认值即可</td>
</tr>
<tr>
<td>autoRedirect</td>
<td><code>bool</code></td>
<td><code>false</code></td>
<td>保存成功后自动跳转</td>
</tr>
<tr>
<td>autoRemoveError</td>
<td><code>bool</code></td>
<td>true</td>
<td>当表单值发生变化时自动移除表单错误信息</td>
</tr>
<tr>
<td>before</td>
<td><code>function</code></td>
<td></td>
<td>表单提交之前事件，返回<code>false</code>可以阻止表单继续提交</td>
</tr>
<tr>
<td>after</td>
<td><code>function</code></td>
<td></td>
<td>单提交之后事件(不论成功还是失败都会触发)，返回<code>false</code>可以中止后续逻辑</td>
</tr>
<tr>
<td>success</td>
<td><code>function</code></td>
<td></td>
<td>成功事件（接口返回状态码为<code>200</code>则判断为成功），返回<code>false</code>可以中止后续逻辑</td>
</tr>
<tr>
<td>error</td>
<td><code>function</code></td>
<td></td>
<td>失败事件（接口返回状态码非<code>200</code>则判断为失败），返回<code>false</code>可以中止后续逻辑</td>
</tr>
</tbody>
</table>
<h3>基本用法</h3>
<pre><code class="language-html">&lt;script&gt;
Dcat.ready(function () {
// ajax表单提交
$('#login-form').form({
validate: true, //开启表单验证
before: function (fields, form, opt) {
// fields 为表单内容
console.log('所有表单字段的值', fields);
if (...) {
// 返回 false 可以阻止表单继续提交
return false;
}
},
success: function (response) {
// data 为接口返回数据
if (! response.status) {
Dcat.error(response.data.message);
return false;
}
Dcat.success(response.data.message);
if (data.redirect) {
Dcat.reload(response.data.value)
}
// 中止后续逻辑（默认逻辑）
return false;
},
error: function (response) {
// 当提交表单失败的时候会有默认的处理方法，通常使用默认的方式处理即可
var errorData = JSON.parse(response.responseText);
if (errorData) {
Dcat.error(errorData.message);
} else {
console.log('提交出错', response.responseText);
}
// 终止后续逻辑执行
return false;
},
});
});
&lt;/script&gt;</code></pre>
<h3>高阶用法</h3>
<p>如果你想要实现更细粒度的控制，可以通过类似下面这种方式自己绑定提交按钮，然后提交表单</p>
<pre><code class="language-js">var $form = $('#login-form');
// 禁用默认提交
$form.on('submit', function () {
return false;
});
// ajax表单提交
function submit() {
Dcat.Form({
form: $form,
success: function (response) {
if (! response.status) {
Dcat.error(response.data.message);
return false;
}
Dcat.success(response.data.message);
location.href = response.data.value;
return false;
},
error: function () {
// 非200状态码响应错误
}
});
}
// h5表单验证
function validateForm() {
$form.validator('validate');
// 如果出现错误，则返回false
if ($form.find('.has-error').length &gt; 0) {
return false;
}
return true;
}
// 绑定登陆按钮点击事件
$form.find('[type=&quot;submit&quot;],.submit').click(function (e) {
// 表单验证
if (validateForm() === false) {
return false;
}
// 提交表单
submit();
return false;
});</code></pre>
<p><a name="validate"></a></p>
<h3>表单验证</h3>
<p><code>Dcat Admin</code>集成了<a href="https://github.com/1000hz/bootstrap-validator">bootstrap-validator</a>组件用于表单前端验证的功能，
<a href="https://github.com/1000hz/bootstrap-validator">bootstrap-validator</a>是一款支持H5表单验证的验证器，只需把验证规则写在表单元素的属性上即可自动开启验证，非常方便。</p>
<h4>添加验证规则</h4>
<pre><code class="language-html">&lt;fieldset class=&quot;form-label-group form-group position-relative has-icon-left&quot;&gt;
&lt;input
minlength=&quot;5&quot; &lt;!-- 加上验证规则 --&gt;
maxlength=&quot;20&quot; &lt;!-- 加上验证规则 --&gt;
required &lt;!-- 加上验证规则 --&gt;
type=&quot;password&quot;
class=&quot;form-control&quot;
name=&quot;password&quot;
&gt;
&lt;div class=&quot;form-control-position&quot;&gt;
&lt;i class=&quot;feather icon-lock&quot;&gt;&lt;/i&gt;
&lt;/div&gt;
&lt;label for=&quot;password&quot;&gt;{{ trans('admin.password') }}&lt;/label&gt;
&lt;!-- 这个加了 .with-errors 样式的 div 即是表单错误信息显示的位置，非常重要 --&gt;
&lt;div class=&quot;help-block with-errors&quot;&gt;&lt;/div&gt;
&lt;/fieldset&gt;</code></pre>
<h4>开启表单验证</h4>
<pre><code class="language-js">$('#xx-form').form({
validate: true
});</code></pre>
<p>效果</p>
<p><img src="https://cdn.learnku.com/uploads/images/202004/26/38389/wJxcYaC9GP.png!large" alt="" />
<img src="https://cdn.learnku.com/uploads/images/202004/26/38389/qdXUaNEMSQ.png!large" alt="" /></p>
<p><a name="extend-validator"></a></p>
<h4>扩展验证规则</h4>
<p>通过<code>Dcat.validator.extend</code>方法可以扩展表单验证规则</p>
<pre><code class="language-js">Dcat.validator.extend('maxlength', function ($el) {
return $el.val().length &gt; $el.attr('data-maxlength');
});</code></pre>
<p>使用自定义规则验证表单</p>
<pre><code class="language-html">&lt;input
type=&quot;input&quot;
class=&quot;form-control&quot;
name=&quot;username&quot;
data-maxlength=&quot;20&quot; &lt;!-- 使用刚刚自定义的验证规则 --&gt;
data-maxlength-error=&quot;已超出输入字符长度限制，请输入20个或以下的字符&quot; &lt;!-- 定义错误信息 --&gt;
/&gt;</code></pre>
<h4>内置验证规则</h4>
<p>更多内置验证规则请参考<a href="http://1000hz.github.io/bootstrap-validator/">bootstrap-validator官方文档</a></p>