jsly 3.0.6 → 3.1.7

package/README.md

@@ -194,4 +194,105 @@ $bus.off('test', listener)
 // 移除所有监听器
 $bus.removeAllListeners()
 
+```
+
+### 文本关键词高亮（highlightKeyword）
+高亮文本中匹配的关键词，支持不区分大小写匹配，并允许自定义标签与样式。
+
+```javascript
+import { highlightKeyword } from 'jsly'
+
+const text = '泡泡音乐是一款非常好用的音乐播放器'
+const result = highlightKeyword(text, '音乐')
+console.log(result)
+// => '泡泡<span style="background-color: #ff0;color: #001;">音乐</span>是一款非常好用的<span style="background-color: #ff0;color: #001;">音乐</span>播放器'
+
+```
+
+自定义标签与样式
+```javascript
+highlightKeyword('Hello World', 'world', {
+tag: 'mark',
+bgColor: '#000',
+color: '#0f0'
+})
+
+```
+
+配置说明
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|---------|------|
+| `text` | `string` | 必填 | 原始文本 |
+| `keyword` | `string` | 必填 | 要高亮的关键词（大小写不敏感） |
+| `config.tag` | `string` | `'span'` | 包裹关键词的标签名 |
+| `config.bgColor` | `string` | `'#ff0'` | 背景颜色 |
+| `config.color` | `string` | `'#001'` | 文本颜色 |
+
+### 基于 requestAnimationFrame 的定时器（rafInterval）
+使用 requestAnimationFrame 实现类似 setInterval 的效果。
+更适合动画、轮播、游戏循环等需要与浏览器帧同步的场景。
+
+```javascript
+import { rafInterval } from 'jsly'
+
+// 每秒执行一次
+const stop = rafInterval(() => {
+  console.log('tick')
+}, 1000)
+
+// 停止执行
+stop()
+```
+
+在 Vue 中使用
+
+```javascript
+import { rafInterval } from 'jsly'
+import { onMounted, onUnmounted } from 'vue'
+
+let stop
+
+onMounted(() => {
+  stop = rafInterval(() => {
+    console.log('frame update')
+  }, 16) // 约 60fps
+})
+
+onUnmounted(() => {
+  stop()
+})
+```
+
+### 基轮询函数（poll）
+用于按固定间隔重复执行任务，直到：
+- 返回结果为 truthy
+- 超时
+- 手动停止
+适用于接口状态查询、等待资源加载、检测条件成立等场景。
+
+```javascript
+import { poll } from 'jsly'
+
+// 轮询接口直到 ready === true
+const { promise, stop } = poll(
+  async () => {
+    const res = await fetch('/api/status').then(r => r.json())
+    return res.ready && res
+  },
+  {
+    interval: 2000, // 每 2 秒执行一次
+    timeout: 10000  // 10 秒超时
+  }
+)
+
+promise
+  .then(data => {
+    console.log('成功：', data)
+  })
+  .catch(err => {
+    console.error('轮询失败：', err)
+  })
+
+// 如需手动停止
+// stop()
 ```

package/dist/index.cjs.js

@@ -7628,6 +7628,196 @@ class EventBus {
 // 导出单例
 const $bus = new EventBus();
 
+/**
+ * 转义正则表达式中的特殊字符。
+ *
+ * @private
+ * @function escapeRegExp
+ * @description
+ * 将字符串中的正则表达式特殊字符（如 `. * + ? ^ $ { } ( ) | [ ] \\`）全部转义，
+ * 以便安全地用于构建正则表达式。通常用于用户输入的关键字过滤，避免因
+ * 正则表达式语法导致的匹配异常。
+ *
+ * @param {string} str - 需要进行转义的原始字符串。
+ * @returns {string} 已转义、可安全用于 RegExp 的字符串。
+ *
+ * @example
+ * escapeRegExp("a+b*c") // => "a\\+b\\*c"
+ */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * 高亮文本中的关键词。
+ *
+ * @function highlightKeyword
+ * @description
+ * 在给定的文本中查找所有匹配的关键词（不区分大小写），并使用带样式的
+ * HTML 标签（默认 `<span>`）包裹，使其以高亮方式显示。该方法适用于搜索
+ * 结果展示、文本匹配提示等场景。
+ *
+ * @param {string} text - 原始完整文本。
+ * @param {string} keyword - 需要高亮显示的关键词。如果为空，则直接返回原文本。
+ * @param {Object} [config] - 配置对象，用于自定义高亮标签和样式。
+ * @param {string} [config.tag="span"] - 包裹关键词的 HTML 标签名。
+ * @param {string} [config.bgColor="#ff0"] - 高亮背景颜色。
+ * @param {string} [config.color="#001"] - 关键词文字颜色。
+ *
+ * @returns {string} 返回插入带样式标签后的 HTML 字符串。
+ *
+ * @example
+ * highlightKeyword(
+ *   "泡泡音乐是一款好用的播放器",
+ *   "音乐"
+ * )
+ * // => '泡泡<span style="background-color: #ff0;color: #001;">音乐</span>是一款好用的播放器'
+ */
+function highlightKeyword(text, keyword, config = {
+  tag: "span",
+  bgColor: "#ff0",
+  color: "#001"
+}) {
+  if (!keyword) return text;
+  const {
+    tag,
+    bgColor,
+    color
+  } = config;
+  const pattern = new RegExp(escapeRegExp(keyword), "gi");
+  const style = `background-color: ${bgColor};color: ${color};`;
+  return text.replace(pattern, match => `<${tag} style="${style}">${match}</${tag}>`);
+}
+
+/**
+ * 基于 requestAnimationFrame 实现的定时器（RAF Interval）
+ *
+ * 功能类似于 setInterval，但内部使用 requestAnimationFrame 驱动。
+ * 相比 setInterval：
+ * - 与浏览器刷新率同步，更平滑
+ * - 页面不可见时会自动暂停（节省性能）
+ * - 不易出现掉帧或时间漂移问题
+ *
+ * 适用于动画、轮播、游戏循环等需要与渲染帧同步的场景。
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} callback - 每次间隔触发时执行的函数。
+ * @param {number} delay - 执行间隔时间（毫秒）。
+ * @returns {() => void} 返回一个停止函数，用于取消循环。
+ *
+ * @example
+ * const stop = rafInterval(() => {
+ *   console.log('每秒执行一次')
+ * }, 1000)
+ *
+ * // 停止
+ * stop()
+ *
+ * @example
+ * // 在 Vue 中使用
+ * let stop
+ * onMounted(() => {
+ *   stop = rafInterval(() => {
+ *     rotate.value += 1
+ *   }, 16)
+ * })
+ *
+ * onUnmounted(() => {
+ *   stop()
+ * })
+ */
+function rafInterval(callback, delay) {
+  if (typeof callback !== 'function') {
+    throw new TypeError('rafInterval expected a function as the first argument');
+  }
+  let start = performance.now();
+  let frameId = null;
+  let stopped = false;
+  function loop(now) {
+    if (stopped) return;
+    const delta = now - start;
+    if (delta >= delay) {
+      callback();
+      // 使用 += 防止时间漂移
+      start += delay;
+    }
+    frameId = requestAnimationFrame(loop);
+  }
+  frameId = requestAnimationFrame(loop);
+  return function stop() {
+    stopped = true;
+    if (frameId) cancelAnimationFrame(frameId);
+  };
+}
+
+/**
+ * 轮询函数（Polling）
+ *
+ * 按指定间隔重复执行异步任务，直到：
+ * 1. 任务返回 truthy 值（成功）
+ * 2. 超时
+ * 3. 被手动停止
+ *
+ * 常用于：
+ * - 接口状态查询
+ * - 等待资源加载完成
+ * - 检测条件成立
+ *
+ * @template T
+ * @param {() => Promise<T> | T} task - 需要轮询执行的函数（支持同步或异步）。
+ * @param {Object} [options]
+ * @param {number} [options.interval=1000] - 每次轮询间隔时间（毫秒）。
+ * @param {number} [options.timeout=0] - 超时时间（毫秒），0 表示不限制。
+ * @returns {{ promise: Promise<T>, stop: () => void }}
+ *
+ * @example
+ * const { promise, stop } = poll(
+ *   () => fetch('/api/status').then(r => r.json()),
+ *   { interval: 2000, timeout: 10000 }
+ * )
+ *
+ * promise.then(res => console.log('成功：', res))
+ */
+function poll(task, {
+  interval = 1000,
+  timeout = 0
+} = {}) {
+  if (typeof task !== 'function') {
+    throw new TypeError('poll expected a function as the first argument');
+  }
+  let stopped = false;
+  let startTime = Date.now();
+  let timer = null;
+  const promise = new Promise((resolve, reject) => {
+    async function execute() {
+      if (stopped) return;
+      try {
+        const result = await task();
+        if (result) {
+          resolve(result);
+          return;
+        }
+        if (timeout && Date.now() - startTime >= timeout) {
+          reject(new Error('Polling timeout'));
+          return;
+        }
+        timer = setTimeout(execute, interval);
+      } catch (err) {
+        reject(err);
+      }
+    }
+    execute();
+  });
+  function stop() {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  }
+  return {
+    promise,
+    stop
+  };
+}
+
 exports.$bus = $bus;
 exports.buildObjFormData = buildObjFormData;
 exports.camelToSnake = camelToSnake;
@@ -7638,6 +7828,9 @@ exports.copyToClipboard = copyToClipboard;
 exports.debounce = debounce;
 exports.deepDiff = deepDiff;
 exports.generateBrowserId = generateBrowserId;
+exports.highlightKeyword = highlightKeyword;
+exports.poll = poll;
+exports.rafInterval = rafInterval;
 exports.randomHash = randomHash;
 exports.sha256 = sha256;
 exports.shallowDiff = shallowDiff;