KWC Shared Utils 使用文档

概述

@kdcloudjs/kwc-shared-utils 是一个为 KWC 项目提供的共享工具库，包含：

• 客户端环境检测（client）
• 平台资源加载器（platformResourceLoader）
• OpenAPI 适配器与认证（openApiAdapter）
• 组件间消息中心（messageService）
• 其他实用模块（如 kingdeeDataService、sendBosPlatformEvent）

安装

npm install @kdcloudjs/kwc-shared-utils

导入

支持 ES Module 和 CommonJS：

// ES Module
import { client, platformResourceLoader, openApiAdapter, messageService } from '@kdcloudjs/kwc-shared-utils'

// CommonJS
const { client, platformResourceLoader, openApiAdapter, messageService } = require('@kdcloudjs/kwc-shared-utils')

消息中心（发布-订阅）

用于 React 组件与 Web Components 之间的解耦通信，支持本地与跨标签广播：

import { messageService } from '@kdcloudjs/kwc-shared-utils'

// 在组件实例上订阅（component 可为 React 组件实例或自定义元素实例）
const off = messageService.subscribe(component, 'user:login', (payload, { fromRemote }) => {
  console.log('用户登录:', payload, '是否远程广播:', fromRemote)
})

// 发布消息（默认同时本地触发并跨标签广播）
messageService.publish('user:login', { id: 'u001', name: 'Alice' })

// 仅本地触发（不广播）
messageService.publish('user:login', { id: 'u001' }, { global: false })

// 取消订阅
off()

// 也可整体取消某组件在某事件上的订阅
messageService.unsubscribe(component, 'user:login')

特性：

• 使用 BroadcastChannel（自动降级到 postMessage）实现跨标签页/iframe 通信
• 每个组件实例的订阅以 WeakMap 管理，自动清理泄漏
• 错误隔离，单个订阅错误不会影响其他订阅者

OpenAPI 适配器与认证

初始化认证并调用接口：

import { openApiAdapter } from '@kdcloudjs/kwc-shared-utils'

await openApiAdapter.initializeAuth({
  endpoint: '/kapi/oauth2/getToken',
  method: 'POST',
  bodyParams: { /* appId、appSecret、nonce 等 */ },
  // 仅内存存储（不持久化），无需也不接受其他存储策略
})

// 发起请求（示例：OpenAPI 服务调用）
const result = await openApiAdapter.doFetch({
  endpointConfig: {
    isv: 'kd', app: 'myapp', form: 'myform', serviceName: 'myservice', version: 'v2'
  },
  params: { query: 'test' }
})

Token 存储安全

• 仅使用 memory（内存存储，不持久化），不支持 session 与 local，以最大限度降低 XSS 风险。
• 推荐由服务端设置 HttpOnly、Secure、SameSite 的 Cookie，通过接口换取临时访问令牌；前端不持久化 token。

平台资源加载器

动态加载外部脚本与样式：

import { platformResourceLoader } from '@kdcloudjs/kwc-shared-utils'

await platformResourceLoader.loadScript(document.head, 'https://example.com/script.js')
await platformResourceLoader.loadStyle(document.head, 'https://example.com/style.css')

特性：

• URL 级缓存，避免重复加载
• 支持 Promise 与回调

客户端检测

检测应用、浏览器与设备：

import { client } from '@kdcloudjs/kwc-shared-utils'

const appName = client.getAppName() // 'yunzhijia' | 'weixin' | 'dingding' 等
const isMobile = client.isMobile()
const browser = client.getBrowserName() // 'chrome' | 'edge' | 'safari' 等

构建与发布

使用 Rollup 构建：

npm run build

输出 dist/，含 CJS 与 ESM 两种格式，按模块分别打包并压缩。

版本

• 当前版本：1.0.0
• 包名：@kdcloudjs/kwc-shared-utils