CKTools

A library by CKylinMC combined all usually-used script segments.

This script should not be not be installed directly. It is a library for other scripts to include with the meta directive // @require https://update.greasyfork.org/scripts/429720/1082330/CKTools.js

Author
CKylinMC
Version
1.6.1
Created
2021-07-22
Updated
2022-08-17
License
GPLv3 License

A library by CKylinMC combined all usually-used script segments.

Included

  • get/getAll method - alias of querySelector/All. Noticed that getAll return array but not nodelist.
  • makeDom DEPRECATED async method - make a node and do something then return the node just created.
    • This function has been deprecated and will removed in future. Please use domHelper for alternative.
  • domHelper method/async method - make node or node tree from anywhere and full customized.
  • getCookies/getUrlParam method - simplified script for using cookies and url params.
  • wait async method - base waiting method, support async.
  • waitForDom async method - wait until specified dom been found.
  • waitForAttribute async method - wait until specified attribute been found.
  • waitForPageVisible async method - wait until page been displayed.
  • addStyle/clearStyles method - an easy way to manage injected styles.
  • EventEmitter class - a simple emitter polyfill emulating nodejs.
  • HoldClick class - a simple tool handling mouse-long-tap for desktop users.
  • dragger.* object - a group of useful tools handling hold-and-drag for desktop users.
  • modal.* object - a ready-to-go simple single-instance modal window.
  • bili.* object - a group of useful tools for bilibili pages.

Documents:

CKTools

一个油猴脚本快速工具合集。

使用方法

在需要的脚本中引用,引用地址在油猴脚本页面顶部已经展示。

不同版本的CKTools会自动覆盖,旧版本会被新版本替换。

1.2版本以前的旧版本不支持互相覆盖,但是安装1.2和更高版本时支持覆盖旧版本。

调用方式

在页面中直接调用 CKTools 即可。

工具说明

CKTools.*

ver (float)

CKTools版本号

get

document.querySelector 的快捷方式。

可以在第二个参数中传入一个Node,将查询范围限制在Node的子元素中。

getAll

document.querySelectorAll 的快捷方式

可以在第二个参数中传入一个Node,将查询范围限制在Node的子元素中。

请注意此方法返回值会被强制转换为数组形式而非原本的NodeList。

domHelper

创建DOM元素的工具,返回创建好的HTMLElement。

请注意如果使用了initAsync数值

参数接受以下几种形式:

  • (options)
  • (tagName, options) (支持旧版domHelper语法)
  • (tagName, initFn) (支持被废弃的makeDom语法)
  • (tagName, asyncInitFn)(支持被废弃的makeDom) (返回Promise)

具体参数解释:

  • tagName string

    要创建的HTMLElement标签名。缺省此值将会使用div 。 请注意,如options.fromoptions.query 等导入方式会覆盖此值。

  • initFn function

    创建HTMLElement后执行的方法,参数是创建的HTMLElement。

  • asyncInitFn asyncFunction

    创建HTMLElement后执行的方法。若传入方法为异步方法,则domHelper也将是异步的。

options.* object 参数解释

options中的所有参数都是可选的。

  • tag string

    定义要创建的HTMLElement标签名。缺省此值将使用div 作为默认标签名创建HTMLElement。

    请注意,fromquery 功能作为导入功能可能会覆盖此值。

  • from HTMLElement | string

    将已有HTMLElement作为要操作的元素,或从HTML字符串代码中导入HTMLElement。若字符串HTML代码中包含多个HTMLElement,则从tagNameoptions.tag 中创建新的HTMLElement包裹导入的HTMLElement。

  • query string

    将选择器传入document.querySelectorbing并用其返回结果作为导入的HTMLElement。

    请注意如果选择器没有返回有效的HTMLElement,那么domHelper会直接返回null值,这是唯一一个会导致domHelper直接返回失败的方式。

  • id string

    设置操作元素的ID

  • html string

    设置操作元素的HTML代码,等效于el.innerHTML

  • text string

    设置操作元素的文字,等效于el.innerText

  • attr object

    批量设置元素的属性。

    格式为:

    {
        属性名: 属性值,
        //如
        'data-custom-attr': 'yes!'
    }
    

    将会调用setAttribute进行赋值。

  • cssText string

    以字符串方式直接写入样式。

  • style / css object

    style和css是等效的。

    批量设置元素的样式,el.style.*的快捷方式。

    格式:

    {
        fontSize: 'x-large',
        'font-weight': 'bold'
    }
    
  • childs HTMLElement | HTMLElement[] | object[] | string

    为操作元素附加子元素,支持多种方式。

    string:

    附加纯文本节点

    HTMLElement:

    直接将传入的元素附加到原元素中

    HTMLElement[]:

    逐个将传入的元素附加到原元素中

    object:

    以对象方式创建或导入元素。

    对象需要包含两个属性:type 和 content

    其中,type为html时,以默认tag为span方式调用domHelper通过content中的html代码字符串导入元素,随后附加到原元素中。

    type为style时,创建style标签,将content中的字符串代码作为style标签内容附加到原元素中,支持额外的scoped 属性。

    type为任意其他值时,递归调用domHelper创建元素并附加到原元素中,其中type将作为tagName传入参数,而content作为第二参数,可以为options,也可以是initFn。不支持异步方式。

  • classList / classnames string | string[]

    classList和classnames等效。

    设置class名,直接设置字符串或设置字符串数组。支持使用空格分隔的字符串。

  • on / listeners object

    on和listeners等效。

    调用el.addEventListener设置监听器。

    格式如:

    {
        'click': e => console.log(e),
        'mouseover': e => console.log(e)
    }
    
  • off object

    on 相似,但是调用el.removeEventListener取消注册监听器。

  • bind object

    创建一个MutationObserver,监听操作元素的所有属性变化,并根据属性名调用传入的回调方法。

    传入格式如下:

    {
        要监听的属性名: 回调方法,
    // 如
        'value': opt=>console.log(opt)
    }
    

    其中会向回调方法中传入的参数:

    {
        target: 观测对象,
        attributeName: 变化的属性名,
        attributeNamespace: 属性命名空间,
        oldValue: 更改前的值,
        newValue: 更改后的值或undefined,
        unbind: (函数)不再监听这个属性变化,
        stopListen: (函数)不再监听这个元素的任何属性变化
    }
    

    请注意每次调用domHelper传入bind参数时都会创建新的观测实例,在元素移除时也会自动移除观测实例。不同的观测实例之间相互独立,请留意观测方式导致的性能问题。

  • append HTMLElement

    将当前元素附加到指定的元素下。传入参数不是HTMLElement时不做任何事。

  • insertBefore HTMLElement

    将当前元素插入的指定元素前。传入参数不是HTMLElement时不做任何事。

  • insertAfter HTMLElement

    将当前元素插入的指定元素后。传入参数不是HTMLElement时不做任何事。

  • init function

    执行自定义方法。此处传入的方法会按照同步方式执行,传入异步方法会丢失返回值。

    自定义方法会接收当前操作元素作为一个参数。

  • initAsync asyncFunction

    执行自定义异步方法。此处传入的方法会按照异步方式执行,并且无论如何都将返回异步结果。

    自定义方法会接收当前操作元素作为一个参数。

以上参数会按照此处列出的顺序进行处理,也就是说init方法和initAsync方法将会最后执行。

makeDom (废弃)

此方法将镜像到domHelper。

addDom

传入一个参数(string | HTMLElement)作为操作元素(字符串会被创建为字符串节点),返回一个DOMItem类实例,此实例支持以下快捷方法:

  • setItem() 替换当前操作元素
  • inside(Node | HTMLElement | string(query)) 将当前操作元素插入到指定节点中。
  • after(Node | HTMLElement | string(query)) 将当前操作元素插入到指定节点之后。
  • before(Node | HTMLElement | string(query)) 将当前操作元素插入到指定节点之前。
  • done() 将操作生效。

类中支持链式调用,在调用done之前,修改不会生效。同时可以多次调用done。

请注意inside、after、before会互相覆盖,同时只能生效一个。

deepClone

深度克隆传入的对象,返回创建的新对象

getCookie

传入一个cookie键名,返回从当前页面获得的对应的cookie。

clearAllCookies

清空当前所有的cookie

getUrlParam

传入一个URL查询键名,返回当前地址栏数据中对应的值。

wait

传入毫秒数,返回一个Promise,Promise将在指定毫秒后设置为resolved。

waitForDom

等待一个指定元素出现。

第一个参数(string)用于在querySelector中查询。

第二个参数(Node)用于指定在某个节点内执行querySelector。

第三个参数指定重试检查次数,默认为20。

第四个参数指定每次重试检查需要等待的毫秒数,默认200。

只有第一个参数是必须的。

等待成功会返回true,否则返回false。(异步)

waitForAttribute

等待一个属性出现且不为null。

第一个参数是属性所在的对象, 第二个参数为属性名。

将会进行50次、每次100毫秒的循环检查,并在成功时返回其值。(异步)

waitForPageVisible

等待页面处于可见状态(如用户切换标签页)。

若当前已经处于可见状态直接结束,否则注册事件等待页面可见。(异步)

addStyle

注入样式。

参数1:字符串形式的css样式,将会注入到style标签中。

参数2:类名,用于辨别注入的样式。

参数3:模式,支持append\unique\update三种模式,对应每次附加、只注入一次、每次替换。

参数4:要将style注入到某个节点,默认为document.head。

clearStyles

传入一个类名,清除所有与类名匹配的style标签。

debounce \ throttle

消抖、节流。第一个方法作为回调,第二个方法作为时长(ms)。

返回一个新的方法,在对应条件后执行回调。

domContains

查询包含指定文字的元素,第一个参数传入查询器用于querySelectorAll,第二个参数传入要包含的文字。

mapReplace

文字的批量替换,第一个参数传入要执行的字符串,第二个参数传入对象,以key:value形式指定要替换的值。

padStart

数字向左填充0,返回字符串。

参数1为原数字,参数2为位数。

fixNum

保留小数位,默认不保留。

参数1为数值,参数2为保留位数。

random.*

  • hex()

    生成随机颜色值

  • shufflwArray(arr)

    打乱数组

  • num(min,max)

    范围随机数

  • fromArray(arr)

    从数组中随机选择1个元素返回

  • from(...args)

    与fromArray相同,但是解构形式。

is.*

  • str(strlikeobj)

    返回是否字符串

  • elementInViewport(element)

    返回元素是否在视口内

  • asyncFn(fn)

    返回方法是否为异步方法

  • darkMode()

    返回当前是否为系统黑色模式

modal.*

  • openModal(title,content)

    打开一个窗口

  • isModalShowing()

    窗口是否正在显示

  • hideModal()

    执行隐藏窗口动画

  • initModal()

    初始化弹窗组件

  • closeModal()

    直接移除弹窗

  • alertModal(title, content, [btntext])

    创建一个alert弹窗,展示指定内容。若btntext不指定则不显示关闭按钮(将无法关闭弹窗,除非调用关闭弹窗方法)。

    btntext为任意字符串时显示按钮,按钮文字为btntext的值。

    异步方法,await将等待弹窗完全打开。

  • blockWindow(block)

    创建弹窗的半透明backdrop,传入参数的真值将控制显隐。

bili.*

  • getCSRFToken()

    返回网页端哔哩哔哩鉴权cookie值 (bili_jct)

  • playerReady()

    返回一个异步对象,判断是否哔哩哔哩播放器已经载入完全。

  • getTotalTime()

    异步返回播放器当前视频总时长

  • getCurrentTime()

    返回播放器当前播放时间

  • setTime(t)

    设置播放器进度

  • play() \ pause()

    控制播放器播放和暂停

  • getInfoByBvid(bvid) \ getInfoByAid(aid)

    根据传入视频号返回fetch到的json数据

class EventEmitter

需要实例化使用。

  • on(eventname, handler)

    注册事件监听器

  • off(eventname, handler)

    解除注册事件监听器

  • clean(eventname)

    清空某个事件下的全部事件监听器

  • emit(eventname, ...args)

    触发事件。

class HoldClick

需要实例化使用

  • constructor(dom, holdingTime=250)

    要注册长按捕获的元素和长按触发阈值

  • bind(dom)

    更换侦测的元素

  • onclick(fn) (offclick)

    注册对应元素点击事件回调。建议用此方式注册click事件避免冲突。

  • onhold(fn) (offhold)

    注册对应元素长按事件回调。

  • onup(fn) (offup)

    注册mouseup事件回调。建议用此方式注册mouseup事件避免冲突。

  • resetCallback(name = “all” [ | “click” | “hold” | “up” ])

    移除全部或指定分类下的事件回调。

  • uninstall()

    解除当前绑定元素的监听器并清空回调

dragger.*

需要配合HoldClick使用。

  • waitForDragger(isDragging) 等待dragging状态匹配
  • regHandler(fn) 注册回调
  • startDrag(e) 开始拖拽功能
  • handleDrag(e) 处理拖拽中状态
  • stopDrag() 结束拖拽功能。

GUID.*

  • get() 获得标准GUID
  • getShort() 获得缩短的GUID