yypkg 工具函数 API 文档 - 文章教程

yypkg 工具函数 API 文档

发布于 2021-09-08 字数 27118 浏览 1066 评论 0

通用 Common

API()

基于 axios 的 API 管理模块,详细文档

debounce(callback, wait, immediate)

函数去抖,每完成等待某个时间后去执行某函数,只希望执行一次,例如防止 input 事件短时间内重复触发

  • @version since 1.0.0
  • @param {Function} callback 回调函数
  • @param {number} wait 等待 wait 毫秒之后才执行
  • @param {boolean} immediate 是否立即执行。v2.0.6 增加
  • @return {Function} 返回
import debounce from 'yypkg/debounce'

element.addEventListener('click', debounce(submit, 200, true), false)
function submit(e) { }

throttle(fn, time)

函数节流,设置一个阀值,在阀值内,将触发的事件合并成一次执行;且当到达阀值,必定执行一次事件。常用于 resizescroll 等事件

  • @version since 1.0.0
  • @param {Function} fn 回调函数
  • @param {Number} time 每隔多长时间执行一次,单位毫秒
import throttle from 'yypkg/throttle'

document.body.addEventListener('scroll', throttle(scroll, 200), false)
function scroll(e) { }

sleep(time)

Promise 版的 setTimeout

  • @version since 1.0.0
  • @param {Number} time 等待多长时间,单位毫秒
import sleep from 'yypkg/sleep'

await sleep(500)

clone(x)

深拷贝

  • @version since 1.0.0
  • @param {Any} x 需要拷贝的对象
  • @return {Any} number / array / function / ...
import { clone, cloneJSON, cloneLoop, cloneForce } from 'yypkg/clone'

clone(x)

deepMerge(target, source)

对象深度合并

  • @version since 2.0.5
  • @param {Object} target 对象1
  • @param {Object} source 对象2
  • @return {Object} 合并后的对象
import deepMerge from 'yypkg/clone'

const m1 = { a: 123, b: 456 }
const m2 = { a: 666 }
deepMerge(m1, m2)
// { a: 666, b: 456 }

type(x, strict)

类型检测,弥补typeof获取类型不准确的问题

  • @version since 1.0.0
  • @param {Any} x 需要检测的对象
  • @param {Boolean} strict 是否严格模式
  • @return {String} number / array / function / ...
import type from 'yypkg/type'

type(x)

路径 URL

getUrlParam(name, url)

获取 URL 上参数

  • @version since 1.0.0
  • @param {String} name 需要获取的参数名
  • @param {String} url 需要被处理的 url,默认为当前 url
  • @return {String} 对应的参数字符串
import getUrlParam from 'yypkg/get-url-param'

const version = getUrlParam('v')
consle.log(version)
// https://yy.com/?v=666
// => '666'

setUrlParam(uri, key, value)

设置/追加 URL 参数

  • @version since 2.0.6
  • @param {String} uri 需要被处理的 url
  • @param {String} key 需要设置或添加的参数的 key
  • @param {String} value 需要设置或添加的参数的 value
  • @return {String} 返回被处理后的新的 url
import setUrlParam from 'yypkg/set-url-param'

const link = setUrlParam('https://www.yy.com/#/detail/4', 'share', 'app')
consle.log(link)
// => 'https://www.yy.com/?share=app#/detail/4'

removeUrlParam(uri, key)

移除 url 中指定的参数(键值)

  • @version since 2.0.7
  • @param {String} uri 需要被处理的 url
  • @param {String} key 需要移除的参数的 key
  • @return {String} 返回移除指定参数后的 url
import removeUrlParam from 'yypkg/remove-url-param'

const link1 = removeUrlParam('https://www.yy.com/?channel=app#/detail/6', 'channel')
consle.log(link1)
// => 'https://www.yy.com/#/detail/6'

const link2 = removeUrlParam('https://www.yy.com/?channel=app&share=wechat#/detail/6', 'channel')
consle.log(link2)
// => 'https://www.yy.com/?share=wechat#/detail/6'

getUrlPath()

获取当前 URL 路径(不带参数)

  • @version since 1.0.0
  • @return {String} 当前url
import getUrlPath from 'yypkg/get-url-path'

const path = getUrlPath()
consle.log(path)
// https://yy.com/music/?v=666
// => 'https://yy.com/'

getAbsoluteUrl(url)

根据相对路径获取绝对路径

  • @version since 1.0.0
  • @param {String} url 相对路径
  • @return {String} 当前绝对路径
import getAbsoluteUrl from 'yypkg/get-absolute-url'

const absUrl = getAbsoluteUrl('/img/logo.png')
consle.log(absUrl)
// https://yy.com/music/index.html
// => 'https://yy.com/img/logo.png'

浏览器 Browser

getUserAgent()

获取浏览器用户代理字符串,返回小写

  • @version since 2.0.0
  • @return {String} 浏览器userAgent
import getUserAgent from 'yypkg/get-user-agent'

const ua = getUserAgent()
consle.log(ua)
// => 'mozilla/5.0 (macintosh; intel mac os x 10_15_4) applewebkit/537.36 (khtml, like gecko) chrome/81.0.4044.138 safari/537.36'

getFirstBrowserLanguage()

获取浏览器设置的第一语言

  • @version since 1.0.0
  • @return {String} 浏览器第一语言名称,未知返回 'unknown'
import getFirstBrowserLanguage from 'yypkg/get-first-browser-language'

const lang = getFirstBrowserLanguage()
consle.log(lang)
// => 'zh'

getBilingual()

获取中英文双语情景下的浏览器语言,跟 getFirstBrowserLanguage() 不同的是,该方法返回结果只有两种,中文(含繁体)统一返回 zh,其他情况(含获取到未知)统一返回 en

  • @version since 2.0.4
  • @return {String} 中文(含繁体)统一返回 'zh',其他情况(含获取到未知)统一返回 'en'
import getBilingual from 'yypkg/get-bilingual'

const lang = getBilingual()
consle.log(lang)
// => 'zh'

getIEVersion()

获取IE浏览器的版本号

  • @version since 1.0.0
  • @return {Number} IE浏览器的版本号,获取失败返回 -1
import getIEVersion from 'yypkg/get-ie-version'

const ie = getIEVersion()
consle.log(ie)
// => 10

getVendor()

获取浏览器供应商的名称

  • @version since 2.0.0
  • @return {string} 浏览器供应商的名称
import getVendor from 'yypkg/get-vendor'

const vendor = getVendor()
consle.log(vendor)
// => 'google inc.'

格式化 Format

createUUID(n)

生成随机的唯一标识号uuid

  • @version since 2.0.0
  • @param {Number} n 标识号的位数
  • @return {String} 唯一标识号
import createUUID from 'yypkg/create-uuid'

const uid = createUUID(12)
consle.log(uid)
// => 'emXApUrWb4Lk'

randomColor()

生成随机的Hex颜色值

  • @version since 1.0.0
  • @return {String} Hex颜色值,六位,不带井号
import randomColor from 'yypkg/random-color'

const color = randomColor()
consle.log(color)
// => 'b79d9c'

trimSpace(str)

字符串裁去空格

  • @version since 1.0.0
  • @param {String} str 被处理的字符串
  • @return {String}
import trimSpace from 'yypkg/trim-space'

const strings = trimSpace('Java Script')
consle.log(strings)
// => 'JavaScript'

dateFormat(date, format)

简易的时间格式化

  • @version since 1.4.0
  • @param {Date} date 时间
  • @param {String} format 格式模板
  • @return {String}
import dateFormat from 'yypkg/date-format'

const now = new Date()
const dataTime = dateFormat(now, 'YYYY-MM-DD hh:mm:ss')
consle.log(dataTime)
// => '2020-04-22 16:41:38'

thousandsDot(num)

对数字进行千分位逗号的格式化

  • @version since 1.4.1
  • @param {Number} num 数字
  • @return {String}
import thousandsDot from 'yypkg/thousands-dot'

const price = thousandsDot(1234567890)
consle.log(price)
// => '1,234,567,890'

padZero(num, digits)

对数字的前缀补充零位

  • @version since 1.4.1
  • @param {Number} num 需要处理的数字
  • @param {Number} digits 位数
  • @return {String}
import padZero from 'yypkg/pad-zero'

const count = padZero(6, 3)
consle.log(count)
// => '006'

numberRange(num, options)

设置数值范围并返回结果

  • @version since 1.11.0
  • @param {Number} num 需要处理的数值
  • @param {Object} options 配置选项
  • @return {Number}
import numberRange from 'yypkg/number-range'

const range = numberRange(6, { min: 7 })
consle.log(range)
// => 7

const range1 = numberRange(20, { min: 5, max: 15 })
consle.log(range1)
// => 15

const range2 = numberRange(10, { min: 15, max: 5 })
consle.log(range2)
// => 10 自动调整区间

const range3 = numberRange(10, { min: 'test', max: 15 })
consle.log(range3)
// => NaN 非法输入

compareVersion(a, b)

简单对比版本号

如 a > b, 返回 1; 如 a = b, 返回 0; 如 a < b, 返回 -1;

  • @version since 1.4.1
  • @param {String} a 版本号1
  • @param {String} b 版本号2
  • @return {Number}
import compareVersion from 'yypkg/compare-version'

const isUpate = compareVersion('1.2.0', '1.4.5')
consle.log(isUpate)
// => -1

stringToDOMElement(string)

原生字符串转为 DOM 元素

  • @version since 1.4.1
  • @param {String} string 字符串
  • @return {DOMElement}
import stringToDOMElement from 'yypkg/string-to-domelement'

const element = stringToDOMElement('test')
consle.log(element)
// => "test"

微信 WeChat

wechatSDK(options)

微信JS SDK。V2.0.5 移除 yoyi 域名签名服务,默认使用 fimo 签名

  • @version since 1.11.4
  • @param {Object} options 配置选项
  • @return {Promise}

options 参数配置

import wechatSDK from 'yypkg/wechat-sdk'

wechatSDK({
  debug: true, // 是否开启微信调试 debug 模式
  signatureApiURL: 'xxx', // 更换 签名服务接口地址,默认为 //server.yoyiapp.com/fimo-wxjssdk
  jsApiList: [], // 微信 API 申请列表,默认为 ['onMenuShareTimeline', 'onMenuShareAppMessage']
  openTagList: [] // since 2.0.11,开放标签列表,默认为 ['wx-open-launch-app', 'wx-open-launch-weapp']
})

share 分享方法

import wechatSDK from 'yypkg/wechat-sdk'

wechatSDK.share({
  title: '分享标题',
  desc: '分享描述',
  link: 'xxx', // 默认值为 window.location.href
  imgUrl: '缩略图'
})

wx

实例对象

import wechatSDK from 'yypkg/wechat-sdk'

(async () => {
  const wx = await wechatSDK()

  wx.ready(function () {
    alert('ok')
  })
})

默认签名支持的域名白名单:

  • *.fimoapp.com
  • *.yoyiapp.com
  • *.yy.com

wechatResetFontSize()

微信禁止缩放网页字体

  • @version since 2.0.0
import wechatResetFontSize from 'yypkg/reset-wechat-font-size'

wechatResetFontSize()

资源 Resources

loadScript(url, retry)

动态加载JavaScript脚本

  • @version since 1.4.1
  • @param {String} url 脚本的url
  • @param {Integer} retry 加载失败时重试的次数,大于等于1的正整数
  • @return {Promise} true 为最终加载成功,false 为最终加载失败
import loadScript from 'yypkg/load-script'

(async () => {
  const isScriptReady = await loadScript('https://abc.com/js/main.js')
  consle.log(isScriptReady)
  // => true
})

loadStyle(url, retry)

动态加载CSS样式表

  • @version since 1.4.1
  • @param {String} url CSS样式表的url
  • @param {Integer} retry 加载失败时重试的次数,大于等于1的正整数
  • @return {Promise} true 为最终加载成功,false 为最终加载失败
import loadStyle from 'yypkg/load-style'

(async () => {
  const isStyleReady = await loadStyle('https://abc.com/css/main.css')
  consle.log(isStyleReady)
  // => true
})

loadStyleText(cssText)

动态插入 CSS 文本样式

  • @version since 1.4.1
  • @param {String} cssText 文本样式
import loadStyleText from 'yypkg/load-style-text'

const cssText = `
.content {
  font-size: 20px;
}
`
loadStyleText(cssText)

sourceLoader(opotions)

资源加载器,常用于资源预加载,支持的资源有:css、js、img(jpg、jpeg、png、gif、webp、mbp)、svga

  • @version since 1.10.0

基本使用

import SourceLoader from 'yypkg/source-loader'

const resources = ['./demo.css', './demo.js']
const loader = new SourceLoader({
  url: resources,
  retry: 3,
})
loader.start()
loader.$on('process', (total, count, url) => {
  console.log(total, count, url)
})
loader.$on('complete', (total) => {
  console.log('total', total)
})
loader.$on('error', (url) => {
  console.error('加载失败', url)
})

点击查看 详细文档

progressController(opotions)

进度控制器,常用于更灵活控制页面加载的进度百分比,可模拟逼真的web页面加载进度

  • @version since 1.10.0
  • @param {Number || Array} from 设置进度起始位置
  • @param {Number || Array} to 设置进度结束位置
  • @param {Number || Array} increment 每次更新的递增量
  • @param {Number || Array} rate 更新频率,即多久更新一次,单位ms
  • @return {Function} ProgressController

基本使用

import ProgressController from 'yypkg/progress-controller'

// 初始配置
let progress = new ProgressController()

progress.start({
  increment: 1,
  rate: 30,
})

// 设置进度到100%
progress.complete(()=>{
  console.log('加载完毕')
})

// 进度加载事件
progress.$on('process', (currentProgress)=>{
  console.log(`当前进度是${currentProgress}`)
})

点击查看 详细文档

forceReload()

强制刷新页面。背景:在某些浏览器内web缓存比较顽固,用自带的刷新有时也不能按预期生效。故强制在url带上随机参数进行刷新

  • @version since 2.0.0
import forceReload from 'yypkg/force-reload'

forceReload()

mocha

Mocha 是一个出名的 测试框架,对于一些前端 Web 项目,我们可以通过 Mocha 进行基本的 BDD 测试

  • @version since 1.4.0
import mocha from 'yypkg/mocha'

function add (x, y) {
  return x + y
}

mocha(async function () {
  const { expect } = chai

  describe('加法函数的测试', () => {
    it('1 加 1 应该等于 2', () => {
      expect(add(1, 1)).to.be.equal(2)
    })
  })
})

点击查看 更多关于 Mocha 的使用

检测 Detect

is 开头的检测类都是使用变量调用,返回 boolean

isWechatBrowser

判断是否为微信浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isWechatBrowser from 'yypkg/is-wechat-browser'

console.log( isWechatBrowser )
// => true

isQQBrowser

判断是否为 QQ 浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isQQBrowser from 'yypkg/is-qq-browser'

console.log( isQQBrowser )
// => true

isWeiboBrowser

判断是否为微博浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isWeiboBrowser from 'yypkg/is-weibo-browser'

console.log( isWeiboBrowser )
// => true

isAndroid

判断是否为 Android 系统

  • @version since 1.0.0
  • @return {Boolean} true | false
import isAndroid from 'yypkg/is-android'

console.log( isAndroid )
// => true

isAndroidPhone

判断是否为 Android 系统的手机设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isAndroidPhone from 'yypkg/is-android-phone'

console.log( isAndroidPhone )
// => true

isAndroidTablet

判断是否为 Android 系统的平板设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isAndroidTablet from 'yypkg/is-android-tablet'

console.log( isAndroidTablet )
// => false

isiOS

判断是否为 iOS 系统

  • @version since 1.0.0
  • @return {Boolean} true | false
import isiOS from 'yypkg/is-ios'

console.log( isiOS )
// => true

isiPhone

判断是否 iOS 系统的 iphone 手机设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isiPhone from 'yypkg/is-iphone'

console.log( isiPhone )
// => true

isiPhoneX

判断是否为 iPhoneX

  • @version since 1.1.0
  • @return {Boolean} true | false
import isiPhoneX from 'yypkg/is-iphonex'

console.log( isiPhoneX )
// => false

isiPad

判断是否为 iPad

  • @version since 1.0.0
  • @return {Boolean} true | false
import isiPad from 'yypkg/is-ipad'

console.log( isiPad )
// => false

isiPod

判断是否为 iPod

  • @version since 1.0.0
  • @return {Boolean} true | false
import isiPod from 'yypkg/is-ipod'

console.log( isiPod )
// => false

isBlackberry

判断是否为黑莓设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isBlackberry from 'yypkg/is-blackberry'

console.log( isBlackberry )
// => false

isMobile

判断是否为移动手机设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isMobile from 'yypkg/is-mobile'

console.log( isMobile )
// => false

isTablet

判断是否为平板设备

  • @version since 1.0.0
  • @return {Boolean} true | false
import isTablet from 'yypkg/is-tablet'

console.log( isTablet )
// => false

isWindowsPhone

判断是否为 Windows 手机

  • @version since 1.0.0
  • @return {Boolean} true | false
import isWindowsPhone from 'yypkg/is-windows-phone'

console.log( isWindowsPhone )
// => false

isWindowsTablet

判断是否为 Windows 平板

  • @version since 1.0.0
  • @return {Boolean} true | false
import isWindowsTablet from 'yypkg/is-windows-phone'

console.log( isWindowsTablet )
// => false

isChrome

判断是否为 Chrome 浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isChrome from 'yypkg/is-chrome'

console.log( isChrome )
// => true

isEdge

判断是否为 Edge 浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isEdge from 'yypkg/is-edge'

console.log( isEdge )
// => true

isIE

判断是否为 IE 浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isIE from 'yypkg/is-ie'

console.log( isIE )
// => true

isSafari

判断是否为 Safari 浏览器

  • @version since 1.0.0
  • @return {Boolean} true | false
import isSafari from 'yypkg/is-safari'

console.log( isSafari )
// => true

交互 UX

scrollToTop

滑动返回顶部

  • @version since 1.14.0
  • @param {Number} scrollY 获取顶部的距离,默认值 0
  • @param {Number} time 动画时长,默认值 200 毫秒
  • @return {Null}
import scrollToTop from 'yypkg/scroll-to-top'

scrollToTop()

Tween

线性运动函数,按指定的动画线性过渡类型的频率返回运动位置

  • @version since 2.0.8
  • @param {number} options.from 起始
  • @param {number} options.to 截止
  • @param {number} options.duration 持续时间,ms
  • @param {string} options.easing 线性过渡类型,可选有:linear、easeIn、easeOut、easeInOut
  • @method Tween.$on('process', (value) => {}) 动画过程持续触发,返回当前运动位置
  • @method Tween.$on('complete', (value) => {}) 动画结束时触发,返回当前运动位置
  • @return void
import Tween from 'yypkg/tween'

const testTween = new Tween({
  from: 0,
  to: 100,
  duration: 1500,
  easing: 'easeInOut'
})
testTween.$on('process', (value: number) => {
  button.style.transform = `translate3d(${value}px, 0px, 0)`
})

appCall

唤起 APP 客户端

  • @version since 2.0.14
  • @param {string} links.universalLink universal links
  • @param {string} links.schemaUrl URL Schemes
  • @param {string} links.fallbackUrl Android 使用的 fallback url
唤起流程
  1. iOS 端 → QQ、微博 提示使用外部浏览器打开 → 如果不传 universalLink 参数,则使用 RUL Schema 打开 → 否则使用 universal link 打开;
  2. Android 端的 微信、微博 提示使用外部浏览器打开 → 否则使用 RUL Schema 打开 → 如果打开失败,则跳转到 fallbackUrl

另外,Android App Links 目前在部分手机的原生浏览器也无法打开 APP,例如华为 mate30、小米 9,所以暂不考虑加入 Android App Links 支持。

import appCall from 'yypkg/app-call'

appCall({
  universalLink: 'https://yypkg.github.io/',
  schemaUrl: 'yypkg://',
  fallbackUrl: 'https://yypkg.github.io/'
})

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2512 文章
30 评论
81913 人气
更多

推荐作者

qq_iQVWB

文章 0 评论 0

gyhjy

文章 0 评论 0

dianjvnan

文章 0 评论 0