快速开始

简介

@jiess/utils 是 Jiess 跨框架生态的核心工具库，提供三大模块：

模块	导入路径	内容
通用工具函数	@jiess/utils	类型判断、深拷贝、日期格式化、防抖节流、路径操作等 31 个函数
环境检测与辅助	@jiess/utils/helper	浏览器/OS/设备检测、响应式代理、网络工具共 18 个函数
Midder 事件总线	@jiess/utils/midder	组件间解耦通信的事件广播订阅器

设计原则

• $ 前缀：所有工具函数以 $ 开头（如 $diff、$clone），视觉上区分工具与业务
• 类型安全：完整的 TypeScript 类型定义，$check 同时作为类型守卫
• 按需引入：包体支持 Tree-shaking，未使用的函数不会被打包
• 跨环境：浏览器和 Node.js 均可运行，Cookie/DOM 相关函数在非浏览器环境自动降级

安装

npm install @jiess/utils
# 或
yarn add @jiess/utils
# 或
pnpm add @jiess/utils

导入方式

// 按需引入工具函数（推荐）
import { $diff, $clone, $check, $debounce1, $dateFormat } from '@jiess/utils'

// 引入环境检测
import { getOSInfo, getDeviceType, getQuery } from '@jiess/utils/helper'

// 引入事件总线（须通过 midder 子模块路径）
import Midder from '@jiess/utils/midder'

导入路径差异说明：

• @jiess/utils（主入口）只导出 31 个 $ 前缀工具函数（具名导出 + 默认对象导出），不包含 Midder。
• @jiess/utils/midder（子模块）以默认导出提供 Midder 类，是引入事件总线的唯一正确路径。
• @jiess/utils/helper（子模块）导出环境检测与辅助函数。

5 分钟上手

场景一：表单提交防抖

import { $debounce1, $check } from '@jiess/utils'

const handleSubmit = (formData: unknown) => {
  $debounce1(() => {
    if ($check(formData, 'object')) {
      // TypeScript 自动推断 formData 为 object
      fetch('/api/submit', { method: 'POST', body: JSON.stringify(formData) })
    }
  }, 500)
}

场景二：跨组件数据同步

import Midder from '@jiess/utils/midder'

// 第一个参数是 Jiess 框架实例，内部用于上下文访问（如 watchEffect 会调用 $jiess.$watchEffect）。
// 仅使用 dispatch/addListener/clean 的事件总线功能时，传入 mock 对象 `{} as any` 即可；
// 若需调用 watchEffect，则须传入具备 $watchEffect 方法的真实 Jiess 实例。
const mockJiess = {} as any

// A 组件发起数据变更
const bus = new Midder(mockJiess, 'appBus', 'multiple')
bus.dispatch('userUpdated', { name: '张三' })

// B 组件监听变更
bus.addListener('userUpdated', (data) => {
  console.log('用户已更新:', data.name) // "张三"
})

场景三：环境适配

import { getDeviceType } from '@jiess/utils/helper'

const device = getDeviceType(navigator.userAgent)
if (device === 'Mobile') {
  import('./mobile-ui')  // 动态加载移动端 UI
} else {
  import('./desktop-ui') // 动态加载桌面端 UI
}

场景四：安全读取深层属性

import { $getByPath } from '@jiess/utils'

const config = { server: { api: { timeout: 3000 } } }
const timeout = $getByPath(config, 'server.api.timeout') // 3000
$getByPath(config, 'server.retry.max') // undefined，而非报错

项目结构

jiess-utils/
├── src/
│   ├── tools/index.ts       # 31 个 $ 前缀工具函数
│   ├── helper/
│   │   ├── index.ts         # customFuction, customAsyncFuction
│   │   ├── environment.ts  # 浏览器/OS/设备检测
│   │   └── jiess.ts        # 响应式代理、URL解析、网络工具
│   └── midder/
│       ├── index.ts         # Midder 入口 + 类型导出
│       ├── Driver.ts        # 触发器
│       └── Listener.ts      # 监听器
├── test/                    # 21 个测试套件 / 592 条用例
└── package.json

文档导航

文档	适用场景
工具函数参考	查阅 $diff、$clone、$dateFormat 等所有工具函数的参数与示例
环境检测与辅助	浏览器/OS/设备检测、Jiess 响应式辅助、动态函数
Midder 事件总线	事件驱动的组件间解耦通信完整指南
最佳实践与FAQ	性能优化建议、常见踩坑、迁移指南