English doc | 中文文档

introduce

A library for detecting idle state of browser. Zero dependency, size of 4.7kb. With powerful APIs. -- inspired by idle-timeout.

what I can do

• running some tasks while browser idling
• auto pause/resume task(s)

install

using npm or yarn

npm install idle-state -S

yarn add idle-state -S

using cdn

<script src="https://xxx.xx.xx/idle-state.min.js"></script>

usage

just pass a callback

import idle from 'idle-state'

const foo = () => {
  console.log('do task foo.')
}
// just pass a callback, `foo` will be called while browser idling
idle(foo)

pass a task-array

import idle from 'idle-state'

const task1 = () => console.log('do task1.')
const task2 = () => console.log('do task2.')

// tasks-array, `task1` & `task2` will be called while browser idling
idle([task1, task2])

config opitons or both callback & config options

import idle from 'idle-state'

const task1 = () => console.log('do task1.')
const task2 = () => console.log('do task2.')

// with config
idle({
  tasks: [task1, task2],
})

// both callback & config options
// in this case task1 & task2 will be converted to an tasks-array [task1, task2]
idle(task1, { tasks: [task2] })

document

The idle function has two arguments

import idle from 'idle-state'

idle(callback, options)

• callback - can be a function or function-array
  • [Function] - considered a single task
  • [Function-array] - considered a tasks-array
• options [Object] - configuration of how task running
  • target [Element | Element-Array] - the target would be watched, which determines whether the state is idling
  • tasks [Function-array] - tasks-array
  • timeout [Number] - the duration after the browser enters the idle state, at which time the task begins to execute
  • interval [Number] - interval of task runing
  • loop [Boolean] - should task(s) runs loopy
  • mousemoveDetect [Boolean] - should detect mousemove event. Mousemove events are frequently triggered in the browser, so put it configurable
  • reqeustDetect [Boolean] - should detect requests(ajax or fetch) on browser
  • events [EventName-array] - name of events, which would be concated(merged) with default value (scroll, keydown, touchmove, touchstart, click)
  • onPause [Function] - called on tasks pause
  • onResume [Function] - called on tasks resume
  • onDispose [Function] - called on tasks dispose

options default value

const noop = () => {}

const defaultOptions = {
  target: document.body,
  tasks: [],
  timeout: 3000,
  interval: 1000,
  loop: false,
  mousemoveDetect: false,
  reqeustDetect: true,
  events: ['scroll', 'keydown', 'touchmove', 'touchstart', 'click'],
  onPause: noop,
  onResume: noop,
  onDispose: noop,
}

methods

you can get an instance from idle() function

import idle from 'idle-state'

const instance = idle(() => {})

instance

• .pause(callback) - pause tasks running
• .resume(callback) - resume paused tasks
• .dispose(callback) - dispose the resource & remove events handler
• .push(task-function) - push a task in current tasks-array
• .timeout(time) - set options.timeout the duration after the browser enters the idle state, at which time the task begins to execute (in milliseconds)
• .interval(time) - set options.interval the tasks running interval (in milliseconds)
• .loop(boolean) - set options.loop should the tasks runs loopy
• .isIdle - get current idle state, return a boolean value

the callback passed by methods ( such as pause(callback) ) has a higher priority than options ( such as options.onPause )

.pause(callback)

instnce.pause()

// with callback
instance.pause(() => console.log('task paused.'))

.resume(callback)

instance.resume()

// with callback
instance.resume(() => console.log('paused task re-running.'))

.dispose(callback)

instance.dispose()

// with callback
instance.dispose(() => console.log('tasks stoped.'))

.push(task)

const task = () => console.log('I am a task.')
// task should be a function
instance.push(task)

.timeout(time)

instance.timeout(2000)

.interval(time)

instance.interval(2000)

.loop(boolean)

instance.loop(true)

get current idle state

import idle from 'idle-state'

const instance = idle(() => {})

// you can get current state by
instance.isIdle // => get a Boolean value

it will get false while browser trigger event [scroll, keydown, touchmove, touchstart, click] by default, you can config options.events, which will replace default options.events

demo

npm run dev

build

npm run build