类型 : T[]

被过滤的阵列 .

从数组中删除重复

import { arrayUnique } from '@alessiofrittoli/web-utils'

const pointer = {}
console.log(arrayUnique([pointer, 'b', pointer, 'c', 'b']))
// Outputs: [ {}, 'b', 'c' ]

类型 : T[]

被过滤的阵列 .

删除相同正则值的数组重复

import { arrayObjectUnique } from '@alessiofrittoli/web-utils'

const arr = [
  { id: 1, name: 'a' },
  { id: 2, name: 'b' },
  { id: 1, name: 'c' }, // duplicate `id`
  { id: 3, name: 'd' },
  { id: 4, name: 'a' }, // duplicate `name`
]

console.log(arrayObjectUnique(arr, 'id'))
// Outputs: [
//     { id: 1, name: 'a' },
//     { id: 2, name: 'b' },
//     { id: 3, name: 'd' },
//     { id: 4, name: 'a' },
// ]

console.log(arrayObjectUnique(arr, 'name'))
// Outputs: [
//     { id: 1, name: 'a' },
//     { id: 2, name: 'b' },
//     { id: 1, name: 'c' },
//     { id: 3, name: 'd' },
// ]

类型 : string[]

转换为串行对象的矩阵 .

基本用途

import { listToArray } from '@alessiofrittoli/web-utils'

console.log(listToArray('1,2, 3, 4').map(Number))
// Outputs: [ 1, 2, 3, 4 ]

类型 : T[]

一大堆块.

基本用途

import { chunkInto } from '@alessiofrittoli/web-utils'

console.log(chunkInto([1, 2, 3, 4, 5], { count: 2 }))
// Output: [ [ 1, 2, 3 ], [ 4, 5 ] ]

console.log(chunkInto([1, 2, 3, 4, 5], { size: 2 }))
// Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]

类型 : Array<T>

已修改的洗牌阵列 .

import { shuffle } from '@alessiofrittoli/web-utils'

console.log(shuffle([1, 2, 3, 4, 5]))

类型 : number

正常指数.

import { normalizeIndex } from '@alessiofrittoli/web-utils'

const array = [0, 1, 2, 3]

console.log(normalizeIndex(2, array.length)) // Outputs: 2
console.log(normalizeIndex(-1, array.length)) // Outputs: 3
console.log(normalizeIndex(-3, array.length)) // Outputs: 1

类型 : number

上个索引.

import { getPreviousIndex } from '@alessiofrittoli/web-utils'

const array = [0, 1, 2, 3]

console.log(getPreviousIndex(array.length, 2)) // Outputs: 1
console.log(getPreviousIndex(array.length, -1)) // Outputs: 2
console.log(getPreviousIndex(array.length, -3)) // Outputs: 0

类型 : number

下个索引.

import { getNextIndex } from '@alessiofrittoli/web-utils'

const array = [0, 1, 2, 3]

console.log(getNextIndex(array.length, 2)) // Outputs: 3
console.log(getNextIndex(array.length, -1)) // Outputs: 0
console.log(getNextIndex(array.length, -3)) // Outputs: 2

• T 数组中的元素类型.

类型 : T[]

在指定位置插入项的新阵列 .

import { insertAfter } from '@alessiofrittoli/web-utils'

console.log(insertAfter([1, 2, 3, 4], 5)) // Outputs: [ 1, 2, 3, 4, 5 ]
console.log(insertAfter(['a', 'c'], 'b', 0)) // Outputs: [ 'a', 'b', 'c' ]
console.log(insertAfter(['a', 'b', 'c', 'e'], 'd', -2)) // Outputs: [ 'a', 'b', 'c', 'd', 'e' ]

• T 存储在阵列中的对象类型 .
• U 关键 T 用于比较.

类型 : number

匹配项的索引,或 -1 当找不到匹配时.

import { findIndexBy } from '@alessiofrittoli/web-utils'

const users = [
  { id: 1, name: 'Ada' },
  { id: 2, name: 'Grace' },
  { id: 3, name: 'Linus' },
]

console.log(findIndexBy({ items: users, field: 'id', value: 2 })) // Outputs: 1
console.log(findIndexBy({ items: users, field: 'name', value: 'Linus' })) // Outputs: 2
console.log(findIndexBy({ items: users, field: 'id', value: 9 })) // Outputs: -1

从 HTTP 响应下载文件

import { downloadBlob } from '@alessiofrittoli/web-utils'

fetch( ... )
  .then( response => response.formData() )
  .then( async data => {
    await Promise.all(
      Array.from( data.entries() )
        .map( async ( [, file ] ) => {
          if ( ! ( file instanceof File ) ) return
          await downloadBlob( file.name, file )
        } )
    )
  } )
  .catch( error => {
    console.error( error )
  } )

弹出时屏蔽文档 HTML 滚动

import { blockScroll } from '@alessiofrittoli/web-utils/dom'

const openPopUpHandler = () => {
  blockScroll()
  // ... handle popup
}

.modal-wrapper {
  position: fixed;
  inset: 0;
  padding-right: var(--scrollbar-size, 0);
}

特定 HTML 元素的块滚动

import { blockScroll } from '@alessiofrittoli/web-utils/dom'

const element = document.querySelector('.css-selector')

if (element) {
  blockScroll(element)
}

弹出关闭时恢复文档 HTML 滚动

import { restoreScroll } from '@alessiofrittoli/web-utils/dom'

const closePopUpHandler = () => {
  // ... handle close
  restoreScroll()
}

恢复特定 HTML 元素的滚动

import { restoreScroll } from '@alessiofrittoli/web-utils/dom'

const element = document.querySelector('.css-selector')

if (element) {
  restoreScroll(element)
}

类型 : HTMLStyleElement[]

• 数组 HTMLStyleElement 对象,每个对象包含来自源样式表的 CSS 规则.
• 失败的样式表被过滤出而不包含在结果中 .

import { cloneStyleSheetList } from '@alessiofrittoli/web-utils/stylesheet'

const styles = cloneStyleSheetList(document.styleSheets)
// do something with cloned stylesheets
// styles.forEach( style => shadowRoot.appendChild( style ) )

类型 : Promise<CloneStyleSheetsReturn>

• 一个承诺,解决 一系列克隆 HTMLStyleElement 财务报告和审定财务报表 HTMLLinkElement 节点.
• 对于内行样式和样式SheetLists,返回 HTMLStyleElement 节点.
• 对于基于 URL 的样式表,返回 HTMLLinkElement 节点(或 HTMLStyleElement 如果获取是 true) (中文(简体) ).
• 失败的操作被默默地忽略.

克隆 StyleSheetList

import { cloneStyleSheets } from '@alessiofrittoli/web-utils/stylesheet'

const styles = await cloneStyleSheets(document.styleSheets)
// do something with cloned dcoument stylesheets
// styles.forEach( style => shadowRoot.appendChild( style ) )

从 URL 复制样式表

import { cloneStyleSheets } from '@alessiofrittoli/web-utils/stylesheet'

const styles = await cloneStyleSheets('/path-to-stylesheet-file.css')

const styles = await cloneStyleSheets({
  url: '/path-to-stylesheet-file-2.css',
  fetch: true,
})

const styles = await cloneStyleSheets([
  '/path-to-stylesheet-file-3.css',
  { url: '/path-to-stylesheet-file-4.css', fetch: true },
])

类型 : reference 实值 GeneratorFunction | AsyncGeneratorFunction

• true 如果给定 reference 是一个 GeneratorFunction 或者说 AsyncGeneratorFunction。 。 。 .
• false 否则.

类型 : reference 实值 GeneratorFunction

• true 如果给定 reference 是一个 GeneratorFunction。 。 。 .
• false 否则.

类型 : reference 实值 AsyncGeneratorFunction

• true 如果给定 reference 是一个 AsyncGeneratorFunction。 。 。 .
• false 否则.

类型 : reference 实值 Generator<T> | AsyncGenerator<T>

• true 如果给定 reference 是一个 Generator 或者说 AsyncGenerator。 。 。 .
• false 否则.

类型 : reference 实值 Generator<T>

• true 如果给定 reference 是一个 Generator。 。 。 .
• false 否则.

类型 : reference 实值 AsyncGenerator<T>

• true 如果给定 reference 是一个 AsyncGenerator。 。 。 .
• false 否则.

类型 : Promise<void>

新的承诺,在指定时间之后得到解决.

import { sleep } from '@alessiofrittoli/web-utils'

const fn = async () => {
  // ...
  await sleep(2000)
  // ...
}

类型 : Promise<Awaited<ReturnType<T>>>

返回新承诺 task 结果一旦实现.

基本用途

import { deferTask } from '@alessiofrittoli/web-utils'

const myLongTask = () => {
  ...
}

button.addEventListener( 'click', () => {
  deferTask( myLongTask )
} )

带有自定义参数

import { deferTask } from '@alessiofrittoli/web-utils'

const myLongTask = ( target: HTMLButtonElement ) => {
  ...
}

button.addEventListener( 'click', event => {
  const target = event.target as HTMLButtonElement
  deferTask( myLongTask, target )
} )

类型 : ( ...args: U ) => Promise<Awaited<ReturnType<T>>>

一个新的处理器,它返回一个新的承诺,返回 task 结果一旦实现.

import { deferCallback } from '@alessiofrittoli/web-utils'

const myLongTask = ( event: Event ) => {
  ...
}

button.addEventListener( 'click', deferCallback( myLongTask ) )

类型 : string

处理过的字符串 .

import { ucFirst } from '@alessiofrittoli/web-utils'

console.log(ucFirst('String value')) // Outputs: 'String value'
console.log(ucFirst('string value')) // Outputs: 'String value'

类型 : string

处理过的字符串 .

import { lcFirst } from '@alessiofrittoli/web-utils'

console.log(lcFirst('String value')) // Outputs: 'string value'
console.log(lcFirst('string value')) // Outputs: 'string value'

类型 : string

转换为骆驼Case的字符串 .

import { toCamelCase } from '@alessiofrittoli/web-utils'

console.log(toCamelCase('font-family')) // Outputs: 'fontFamily'
console.log(toCamelCase('background-color')) // Outputs: 'backgroundColor'
console.log(toCamelCase('-webkit-align-content')) // Outputs: 'WebkitAlignContent'
console.log(toCamelCase('some value')) // Outputs: 'someValue'
console.log(toCamelCase('some_value')) // Outputs: 'someValue'
console.log(toCamelCase('some value_with mixed_Cases')) // Outputs: 'someValueWithMixedCases'
console.log(toCamelCase('-string@with#special$characters')) // Outputs: 'StringWithSpecialCharacters'

类型 : string

转换为 kebab 的字符串 .

import { toKebabCase } from '@alessiofrittoli/web-utils'

console.log(toKebabCase('fontFamily')) // Outputs: 'font-family'
console.log(toKebabCase('backgroundColor')) // Outputs: 'background-color'
console.log(toKebabCase('string with spaces')) // Outputs: 'string-with-spaces'
console.log(toKebabCase('string_with_underscores')) // Outputs: 'string-with-underscores'
console.log(toKebabCase('WebkitAlignContent')) // Outputs: '-webkit-align-content'
console.log(toKebabCase('some value_with mixed_Cases')) // Outputs: 'some-value-with-mixed-cases'
console.log(toKebabCase('-string@with#special$characters')) // Outputs: '-string-with-special-characters

类型 : string

字符串 input。 。 。 .

import { stringifyValue } from '@alessiofrittoli/web-utils'

console.log(stringifyValue(new Date('Sat, 20 Apr 2025 16:20:00 GMT')))
// Outputs: '2025-04-20T16:20:00.000Z'

console.log(stringifyValue(null))
// Outputs: 'null'

console.log(stringifyValue({ prop: 'value', prop2: true }))
// Outputs: '{"prop":"value","prop2":true}'

console.log(stringifyValue([1, 2, true, null, () => {}]))
// Outputs: '[1,2,true,null,null]'

console.log(
  stringifyValue(
    new Map([
      ['key', 'value'],
      ['key2', 'value'],
    ]),
  ),
)
// Outputs: '[["key","value"],["key2","value"]]'

console.log(
  stringifyValue(
    new Headers({
      key: 'value',
      key2: 'value',
    }),
  ),
)
// Outputs: '[["key","value"],["key2","value"]]'

console.log(stringifyValue(true)) // Outputs: 'true'
console.log(stringifyValue(false)) // Outputs: 'false'
console.log(stringifyValue(0)) // Outputs: '0'
console.log(stringifyValue(420)) // Outputs: '420'

console.log(stringifyValue(undefined)) // Outputs: ''
console.log(stringifyValue(() => {})) // Outputs: ''
console.log(stringifyValue(new Promise<void>(resolve => resolve()))) // Outputs: ''

类型 : T | undefined

• 解析 input。 。 。 .
• undefined 若无 input 或为空 string 给出.

import { parseValue } from '@alessiofrittoli/web-utils'

console.log(parseValue<Date>(stringifyValue(new Date())))
// Outputs: current Date object.

console.log(parseValue<number>('12345')) // Outputs: 12345
console.log(parseValue()) // Outputs: undefined
console.log(parseValue(' ')) // Outputs: undefined

console.log(parseValue<true>(stringifyValue(true)))
// Outputs: true

console.log(parseValue(stringifyValue({ key: 'value' })))
// Outputs: { key: 'value' }

console.log(parseValue(stringifyValue([1, 2, 3, 4, 5])))
// Outputs: [ 1, 2, 3, 4, 5 ]

console.log(parseValue('String value')) // Outputs: 'String value'

import { parameterized } from '@alessiofrittoli/web-utils'

const data = {
  value: 'parameterized',
}

console.log(parameterized`My string with ${data.value} values.`) // [ 'My string with ? values.', [ 'parameterized' ] ]

类型 : boolean

• false 若为 window 未定义或如果 document 目前不匹配给定的 query。 。 。 .
• true 否则.

检查当前设备是否面向地貌

import { getMediaMatches } from '@alessiofrittoli/web-utils'

console.log(!getMediaMatches('(orientation:portrait)'))

类型 : WindowProxy | null

• (单位:千美元) WindowProxy 如果浏览器成功打开了新的浏览上下文,则返回对象.
• null 如果浏览器无法打开新的浏览上下文, 则返回, 例如因为它被浏览器弹出屏蔽.

重聚焦先前打开的弹出

import { openBrowserPopUp } from '@alessiofrittoli/web-utils/browser-popup'

let windowProxy: WindowProxy | null = null

const clickHandler = () => {
  if (windowProxy && !windowProxy.closed) {
    return windowProxy.focus()
  }

  windowProxy = openBrowserPopUp({
    url: {
      pathname: '/',
      query: { key: 'value' },
    },
  })
}

重新使用弹出

import { openBrowserPopUp } from '@alessiofrittoli/web-utils/browser-popup'

const clickHandler = () => {
  openBrowserPopUp({
    context: 'some-context-name',
    url: {
      pathname: '/',
      query: { key: 'value' },
    },
  })
}

const clickHandler2 = () => {
  openBrowserPopUp({
    context: 'some-context-name',
    url: '/other-path',
  })
}

类型 : boolean

• true 如果支持文档中的图片.
• false 否则.

import { isDocumentPictureInPictureSupported } from "@alessiofrittoli/web-utils/picture-in-picture";

if ( isDocumentPictureInPictureSupported() ) {
  ...
}

import { Exception } from "@alessiofrittoli/exception";
import { requiresDocumentPictureInPictureAPI, ErrorCode } from "@alessiofrittoli/web-utils/picture-in-picture";

const myFunction = () => {
  requiresDocumentPictureInPictureAPI()
  ...
}

try {
  myFunction()
} catch ( _err ) {
  const err = _err as Error

  const error = (
    Exception.isException<string, ErrorCode>(err)
      ? err
      : (
        new Exception(
          err.message,
          {
            code  : ErrorCode.UNKNOWN,
            name  : err.name,
            cause : err,
          }
        )
      )
  )

  switch ( error.code ) {
    case ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED:
      console.warn( 'Document Picture-in-Picture is not supported.' )
      break
    default:
      console.error( 'Unknown error', error )
  }
}

类型 : Promise<OpenDocumentPictureInPicture>

• 一个新的承诺,解决文件图片和图片结果 window 的上下文.

简单使用

import { openDocumentPictureInPicture, ErrorCode } from '@alessiofrittoli/web-utils/picture-in-picture'
import { Exception } from '@alessiofrittoli/exception'

const openPictureInPicture = async () => {
  try {
    const content = document.createElement('div')

    const { window } = await openDocumentPictureInPicture()

    window.document.body.appendChild(content)
  } catch (_err) {
    const err = _err as Error

    const error = Exception.isException<string, ErrorCode>(err)
      ? err
      : new Exception(err.message, {
          code: ErrorCode.UNKNOWN,
          name: err.name,
          cause: err,
        })

    switch (error.code) {
      case ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED:
        console.warn('Document Picture-in-Picture is not supported.')
        break
      default:
        console.error('Unknown error', error)
    }
  }
}

装入渲染屏蔽样式

import { openDocumentPictureInPicture, ErrorCode } from '@alessiofrittoli/web-utils/picture-in-picture'
import { Exception } from '@alessiofrittoli/exception'

const openPictureInPicture = async () => {
  try {
    const content = document.createElement('div')

    const { window } = await openDocumentPictureInPicture({
      styles: {
        url: '/important-stylesheet-fetched-before-opening.css',
        fetch: true,
      },
    })

    window.document.body.appendChild(content)
  } catch (error) {
    // ...
  }
}

类型 : boolean

• true 如果设备在执行此函数时处于肖像取向.
• false 否则.

检查当前设备是否面向地貌

import { isPortrait } from '@alessiofrittoli/web-utils'

console.log(!isPortrait())

类型 : Connection

定义网络状态的对象和 NetworkInformation。见 Connection 用于更多信息的接口.

import { getConnection } from '@alessiofrittoli/web-utils'

const { network } = getConnection()

console.log(network?.effectiveType)

import type { RawCookie, ParsedCookie, ParsedCookieMap } from '@alessiofrittoli/web-utils/cookie'
import { Priority, SameSite } from '@alessiofrittoli/web-utils/cookie'

Priority 数字

Cookie优先级.

SameSite 数字

控制是否发送有跨地点请求的饼干,为防范跨地点请求的伪造袭击提供某种保护(中国证监会) (中文(简体) ).

RawCookie<K, V>

在解析前代表 Cookie 属性的接口 .

ParsedCookie<K, V>

解析后代表 Cookie 属性的界面 .

ParsedCookieMap<K, V>

地图上的Cookie.

Cookie.parse<K, V>()

将给定的饼干参数分析为 Cookie 地图 .

import { Cookie } from '@alessiofrittoli/web-utils/cookie'

const cookie = Cookie.parse({
  name: 'cookiename',
  value: { test: 'value' },
  path: '/specific-path',
  priority: Priority.High,
  expires: Date.now() + 20 * 60 * 1000,
  domain: 'example.com',
  secure: true,
  httpOnly: true,
  sameSite: SameSite.Lax,
  maxAge: Date.now() + 30 * 60 * 1000,
  partitioned: true,
})

Cookie.toString<K, V>()

将准备保存的 Cookie 绑定.

import { Cookie } from '@alessiofrittoli/web-utils/cookie'

document.cookie = Cookie.toString({
  name: 'cookiename',
  value: { test: 'value' },
  path: '/specific-path',
  priority: Priority.High,
  expires: Date.now() + 20 * 60 * 1000,
  domain: 'example.com',
  secure: true,
  httpOnly: false,
  sameSite: SameSite.Lax,
  maxAge: Date.now() + 30 * 60 * 1000,
  partitioned: true,
})

Cookie.fromString<K, V>()

把饼干串分析成饼干地图.