114. 前端JavaScript(二)jQuery、进度条等

本主题接着《前端JavaScript(一)》讲述,推荐按序号阅读

核心库core/jquery

该库用于加载大名鼎鼎的jquery,在Drupal8.7中使用的是v3.2.1版本,此时最新的jquery版本是v3.4.1,网络上有v3.2.1版本的chm格式中文参考手册下载,drupal中大多重要库依赖jquery,本主题不做介绍,但务必学会使用,这是Drupal前端基础也是很多web项目的基础

该库还加载了以下js文件:

  /core/assets/vendor/jquery/jquery-extend-3.4.0.js

作用是为v3.4.0以下版本的jquery重新定义jQuery.extend方法,该方法用于合并对象,或者为jQuery对象增加方法

 

核心库core/jquery.once

加载/core/assets/vendor/jquery-once/jquery.once.min.js,该库依赖于jquery库,jquery对象可视为一个元素集对象,用于对jquery对象执行某种操作时,保证jquery对象中每个元素仅被执行一次,该库使用频率很高,但实现却很简单,在内部以是否添加标记的方式判断元素是否已被执行过,她扩展了jquery对象,在原型上添加了以下三个方法(在jquery对象上均可使用这些方法):

once(id)

返回被id过滤后的jquery对象,参数id是一个字符串,如果没有传递将采用默认值“once”,在jquery对象中的元素上如果存在id标识说明是被执行过的,不存在则没有,以此方式判断是否被执行过,返回的jquery对象中每个元素会在内部被id标记,换句话说在返回对象上再次以相同id调用once(id)将返回空

removeOnce(id)

移除jquery对象中元素的id标识,返回的jquery对象仅包括被id标记过的那些元素,但返回时已经被移除了标记

findOnce(id)

返回被id过滤后的jquery对象,其中仅保留被id标记过的元素

 

核心库core/classList

这是一个垫片库,用于跨浏览器实现元素的classList属性支持,有些浏览器品牌或同一个品牌浏览器的早期版本不支持元素的classList属性,或者支持不统一,该库解决兼容问题,让元素的classList属性有一个统一的接口,便于用户操作元素的类属性,是在原型上修改的,因此所有元素对象均可用,元素的classList属性有以下方法:

add( String [, String] )

添加指定的类值,可以一次性传递多个参数以添加多个类,如果这些类已经存在于元素的属性中,那么它们将被忽略。

remove( String [,String] )

删除指定的类值,同样可以传递多个参数以删除

item ( Number )

按集合中的索引返回类值。

toggle ( String [, force] )

当只有一个参数时:切换 class value; 即如果类存在,则删除它并返回false,如果不存在,则添加它并返回true

当存在第二个参数时:如果第二个参数的计算结果为true,则添加指定的类值,如果计算结果为false,则删除它

contains( String )

检查元素的类属性中是否存在指定的类值。

replace( oldClass, newClass )

用一个新类替换已有类。

 

核心库core/drupal.active-link

文件:core/misc/active-link.es6.js

加载后便运行,立即添加一个行为对象,在文档就绪时为页面中的当前链接添加类:“is-active”,在卸载事件(unload)发生时取消这个类;如果语言、路径、查询参数均与当前页面相同,则这个链接视为激活链接(当前链接),判断依据保存在元素的以下属性中:

 “data-drupal-link-system-path

 “hreflang

 “data-drupal-link-query

当前页面的这些信息保存在全局设置对象drupalSettings

 

核心库core/drupal.progress

文件:core/misc/progress.es6.js

用于实现进度条提示,进度条原理是在页面显示一个进度条,然后每隔一段时间向服务器请求进度数据,然后更新,该库依赖jquery;需要使用进度条的库需要声明对她的依赖,使用示例如下:

function testProgress() {
  let bar = new Drupal.ProgressBar('yunke');
  document.body.appendChild(bar.element[0]);
  let percent = 0;
  let timer = setInterval(function () {
    bar.setProgress(++percent, '进度消息', '进度label');
    if (percent >= 100) {
      clearTimeout(timer);
    }
  }, 100)
}

如果在文档就绪时执行该函数,将在页尾模拟现实一个进度条,说明如下:

实例化:

  new Drupal.ProgressBar(id, updateCallback, method, errorCallback);

将得到一个进度条对象,对应的进度条页面元素是:

      <div id="${id}" class="progress" aria-live="polite">
      <div class="progress__label">&nbsp;</div>
      <div class="progress__track"><div class="progress__bar"></div></div>
      <div class="progress__percentage"></div>
      <div class="progress__description">&nbsp;</div>
      </div>

可通过该元素中相关类属性控制进度条外观,实例化后进度条元素并没有插入DOM,构造方法参数:

id:为该进度条元素的id属性值

updateCallback:每次执行进度条更新后的回调,其参数依次为更新百分比、更新消息、进度条对象

method:向服务器获取进度数据时使用的http方法,getpost,默认为get

errorCallback:发生错误时的回调,参数为进度条对象

这些参数都保存在进度条对象对应的属性上(属性名同参数名),这里假设进度条对象的变量名为bar,也就是bar.idbar.updateCallbackbar.methodbar.errorCallback

进度条对象还有一个元素属性bar.element,保存对应的进度条元素,在实例化进度条对象后需要将其插入DOM才可见,她是一个jQuery对象,所以插入时需要采用bar.element[0]以便转化为DOM对象,进度条对象有一些方法被定义在她的原型上,插入后可用这些方法进行相关操作,如下:

bar.setProgress(percentage, message, label)

更新进度条,并在每次更新后执行更新回调,参数如下:

percentage:整数,0-100之间,代表百分比

message:描述消息

label:进度条标题

bar.startMonitoring(uri, delay)

开始执行进度条更新动作,也意味着开始执行任务,参数:

uri:获取进度数据的服务器url

delay:每隔多少毫秒执行一次更新数据请求,也可以理解为执行一次进度条更新

bar.stopMonitoring()

停止执行更新数据请求,并删除进度条对象上保存的uri地址

bar.sendPing()

向服务器发起请求获得更新数据,要求服务器返回json数据,格式如下:

 status:状态码,如果为0则视为服务器端发生错误

 data:发生错误时(状态码为0)返回的消息

 percentage:整数,0-100之间,代表百分比

 message:用于进度条显示的描述消息

 label:用于进度条显示的标题

在成功发起后将设置下一次发起任务,如果服务器端或ajax错误将不再更新进度条

bar.displayError(string)

在服务器端发生错误或ajax错误时显示错误消息,并执行错误回调,当显示错误时进度条将被隐藏

 

核心库core/ drupal.timezone

文件:core/misc/timezone.es6.js

添加一个行为对象,在文档就绪时查找具备类属性“timezone-detect”的元素,并为其自动设置用户所在的时区,值如“Asia/Shanghai”,被找到的元素应当是一个表单元素,用来自动侦查用户时区,时区信息的获取是通过收集浏览器的特征并发送给后端,由服务器返回的,服务器控制器为:

\Drupal\system\Controller\TimezoneController::getTimezone

获取时采用同步方式,这意味着取回数据前浏览器会被暂时冻结

本系列后续有一期主体全面介绍时区,这里仅是关于前端的一个简略片段

 

 

本书共130小节:

评论 (写第一个评论)