subscribers.js

subscribers.js 小巧且实用的发布/订阅工具库！

<script src="https://cdn.jsdelivr.net/gh/yaohaixiao/subscribers.js/subscribers.min.js"></script>
Download Zip

Publish

emit(topic, data[, async = true])

Description

emit()方法用来发布订阅主题信息。

subscribers.js 默认是采用异步方式发布的。以确保在消费者处理主题时，主题的发起者不会被阻止。 当然 emit() 方法也支持同步主题发布。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

data
Type：
Object

（必须）消息传递的数据对象。

async
Type：
Boolean
Default：
true

(可选) 是否异步发布。默认值：true。

  • 当 async 设置为 true（默认） 时，异步发布；
  • 当 async 设置为 false 时，同步发布；

Returns

Type：
subscribers。

subscribers 对象，以便实现链式调用。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log(msg)
}

subscribers.on('author', handler)
subscribers.on('career', handler)
subscribers.on('years', handler)

// 异步发布
subscribers.emit('author', 'ok') // -> 'ok'

// 同步发布
// 延迟10毫秒：应该看输出 ok 后输出 programmer
subscribers.emit('career', 'programmer', false) // -> 'programmer'

notify(topic, data)

Description

同步发布订阅主题信息。

Parameters

topic
Type：
String

（必须）主题名称。

data
Type：
Object

（必须）消息传递的数据对象。

Returns

Type：
subscribers。

subscribers 对象，以便实现链式调用。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log(msg)
}

subscribers.on('author', handler)
subscribers.on('career', handler)
subscribers.on('years', handler)

// 依次输出：'author'、'career'、'years'
subscribers.notify('author', 'ok') // -> 'ok'
subscribers.notify('career', 'programmer') // -> 'programmer'
subscribers.notify('years', 19) // -> 19

Subscribe

on(topic, handler)

Description

on() 方法用来订阅主题，并给出处理器函数。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

handler
Type：
Function

（（必须）主题的处理器函数。

Returns

Type：
String。

唯一的 token 字符串，例如：'guid-1'。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (author) => {
  console.log(`Author: ${author}`)
}

subscribers.on('author', handler)

// 支持命名空间形式的主题的订阅
subscribers.on('author.career', handler)
subscribers.on('author.career.years', handler)

subscribers.emit('author', 'Yaohaixiao') // -> `Author: Yaohaixiao`
subscribers.emit('author.career', 'Programmer') // -> `Author: Programmer`
subscribers.emit('author.career.years', 23) // -> `Author: 23`

once(topic, handler)

Description

once() 方法用来订阅主题，并给出处理器函数，仅执行一次。

Parameters

topic
Type：
String

（必须）主题名称。

handler
Type：
Function

（（必须）主题的处理器函数。

Returns

Type：
String。

唯一的 token 字符串，例如：'guid-1'。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = () => {
  console.log('author is Robert')
}

subscribers.once('author', handler)

// 发布消息
subscribers.emit('author')

// 再次发布 handler 将不再执行
subscribers.emit('author')

all(handler)

Description

all() 方法用于订阅所有主题消息发布，任何消息发布都会执行 handler() 处理器。

Parameters

handler
Type：
Function

（（必须）处理器函数。

Returns

Type：
String。

唯一的 token 字符串，例如：'guid-1'。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log(`handler：${msg}`)
}

const callback = (msg) => {
  console.log(`handler：${msg}`)
}

subscribers.on('author', handler)
subscribers.on('career', handler)

// 监听所有消息
subscribers.all(callback)

// 发布消息
subscribers.emit('author', 'Robert')
// -> 'handler：Robert'
// 每次都会触发 all() 方法的订阅处理方法
// -> 'callback：Robert'
subscribers.emit('career', 'Programmer')
// -> 'handler：Programmer'
// -> 'callback：Programmer'

Unsubscribe

off(topic[, token])

Description

off() 用来取消订阅主题。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

token
Type：
Function | String

（可选）订阅主题的处理器函数或者唯一 Id 值。

  • 为传递 token 参数：取消指定 topic 的订阅；
  • 传递 token 参数：仅删除 topic 订阅信息中与 token 对应的事件处理器

Returns

Type：
subscribers。

subscribers 对象，以便实现链式调用。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log('handler:', msg)
}

const callback = (msg) => {
  console.log('callback:', msg)
}

subscribers.on('author', handler)

const token = subscribers.on('career', handler)
const guid = subscribers.on('career', handler)

// 取消订阅 author 主题
subscribers.off('author', handler)

// 删除订阅 career 主题下的 handler 处理器
subscribers.off('career', token)

// 删除订阅 career 主题下的 callback 处理器
subscribers.off('career', guid)

// 订阅 career 主题下2个处理器都删除后
// 会取消整个 author 主题订阅，因此再发布 author 主题消息
// 不会有任何反应
subscribers.emit('career', 'web developer')

remove(topic)

Description

remove() 删除特定（单个或多个） topic 主题的订阅者信息。

Parameters

topic
Type：
String | Array

（必须）主题名称。

  • String 类型：删除单个 topic 主题的订阅者信息;
  • Array 类型：删除多个 topic 主题的订阅者信息；

Returns

Type：
subscribers。

subscribers 对象，以便实现链式调用。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log('handler:', msg)
}

const callback = (msg) => {
  console.log('callback:', msg)
}

subscribers.on('author', handler)
subscribers.on('publish', callback)

// 删除 author 主题相关的所有信息
subscribers.remove('author')

// 同时删除 author 和 publish 主题相关的所有信息
subscribers.remove(['author', 'publish'])

clear()

Description

clear() 方法用于清理所有订阅者（主题和处理器的）信息。

Returns

Type：
subscribers。

subscribers 对象，以便实现链式调用。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log('handler:', msg)
}

subscribers.on('author', handler)
subscribers.on('author.career', handler)
subscribers.on('author.career.years', handler)

// 清理所有订阅者（主题和处理器的）信息
subscribers.clear()

subscribers.has() // -> false

Utils

get([topic])

Description

get() 方法用来获取全部或者包含 topic 主题或者订阅 token 的订阅者信息。

Parameters

topic
Type：
String

（可选）主题名称。

  • 不传递 topic 参数，返回全部订阅者信息；
  • 传递 topic 参数
    • 如果是 topic 主题：返回包含 topic 主题的订阅者信息；
    • 如果是订阅 token：返回包含此 token 信息的 topic 主题的订阅者信息；

Returns

Type：
Array | Object。

返回全部或者包含 topic 主题或者订阅 token 的订阅者信息。

import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log('handler:', msg)
}

subscribers.on('author', handler)
subscribers.on('career', handler)
subscribers.on('years', handler)

const token = subscribers.on('years', handler)

// 获取 author 主题订阅者信息
subscribers.get('author')
// -> 返回 author 主题的订阅信息
// [
//   topic: 'author',
//   callback: handler,
//   token: 'guid-1'
// ]

subscribers.get(token)
// -> 返回 career 主题的订阅信息
// [
//   topic: 'career',
//   callback: handler,
//   token: 'guid-2'
// ]

// 获取所有订阅者信息
subscribers.get()
// -> 返回所有主题的订阅信息
// {
//   'author': [
//     topic: 'author',
//     callback: handler,
//     token: 'guid-1'
//   ]
//   'career': [
//     topic: 'career',
//     callback: handler,
//     token: 'guid-2'
//   ]
//   'years': [
//     topic: 'years',
//     callback: handler,
//     token: 'guid-3'
//   ]
// }

has([topic, isDirect = true])

Description

has() 方法判断是否存在指定或者包含 topic 的订阅者信息。

Parameters

topic
Type：
String

（可选）主题名称。

  • 传递 topic 参数：判断指定 topic 或者消息主题的命名空间中包含 topic 的订阅信息；
  • 不传递 topic 参数：判断是否包含任何订阅信息；
isDirect
Type：
Boolean

（可选）是否为指定 topic，默认值: true。

  • true：匹配完全相同的主题或者主题的命名空间中包含 topic 的订阅；
  • false：只匹配与指定 topic 主题完全相同的主题；

Returns

Type：
Boolean。
  • true：有相关的订阅信息；
  • false：无相关的订阅信息；
import subscribers from '@yaohaixiao/subscribers.js/subscribers'

const handler = (msg) => {
  console.log('handler:', msg)
}

subscribers.on('author', handler)
subscribers.on('author.career.years', handler)

subscribers.has('author.career')
// => true - 因为包含 author 主题

subscribers.has('author.career.year')
// => true 因为有完全匹配的主题

subscribers.has('author.career', false)
// => false 因为没有完全匹配的主题

subscribers.has()
// => true

Copyright © 2023 Robert Yao, all right reserved.

Code licensed under MIT License · Documentation licensed under CC BY 3.0

View on GitHub · Issues