@bi-nova/core

NovaSDK 核心包，提供跨平台适配器和插件系统。

支持环境：H5（浏览器）、微信小程序、支付宝小程序。

安装

::: code-group

pnpm add @bi-nova/core

npm install @bi-nova/core

:::

快速开始

⚠️ 重要提示：

• 微信小程序/支付宝小程序：必须设置 autoEnv: true 或手动指定适配器，否则网络请求、存储等功能将无法正常使用
• H5 应用：可省略 autoEnv（默认使用 WebAdapter）

微信小程序

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 wx.request / wx.getStorageSync 等原生 API
})

或者手动指定适配器：

import { createNova, WechatAdapter } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})

支付宝小程序

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // ⚠️ 小程序环境必须开启，使用 my.request / my.getStorageSync 等原生 API
})

H5 应用（浏览器）

import { createNova } from '@bi-nova/core'

const nova = createNova({
  appId: 'your-app-id',
  // autoEnv 可省略，默认使用 WebAdapter（fetch / localStorage）
})

核心概念

适配器（Adapter）

适配器抹平不同平台的 API 差异，所有适配器均实现 AdapterInterface：

| 方法 | 说明 | |------|------| | request(url, options) | 发起网络请求 | | storage.get(key) | 读取本地存储 | | storage.set(key, value) | 写入本地存储 | | navigate(url) | 页面跳转 | | getEnv() | 返回当前环境标识 |

内置适配器：

| 适配器 | 环境 | 底层实现 | |--------|------|----------| | WebAdapter | H5 / 浏览器 | fetch / localStorage / location.href | | WechatAdapter | 微信小程序 | wx.request / wx.getStorageSync / wx.navigateTo | | AlipayAdapter | 支付宝小程序 | my.request / my.getStorageSync / my.navigateTo |

插件系统

通过 nova.use(plugin) 注册插件，插件需满足 Plugin 接口：

interface Plugin {
  name: string
  install(sdk: NovaSDK): void
}

示例：

import { createServices } from '@bi-nova/services'

nova.use(createServices({ env: 'sit', debug: true }))

同名插件仅安装一次，重复调用 use() 会跳过并打印警告。

API

createNova(config)

工厂函数，创建 NovaSDK 实例。

参数：NovaConfig

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|:----:|--------|------| | appId | string | 是 | - | 应用标识。当前版本暂未使用，可填写任意业务标识，预留用于未来功能扩展 | | autoEnv | boolean | 否 | false | 自动检测环境并选择适配器。小程序环境必须设为 true，否则网络请求、存储等功能将无法使用 | | adapter | AdapterInterface | 否 | - | 手动指定适配器（优先级高于 autoEnv）。如 new WechatAdapter() |

返回值： NovaSDK 实例

适配器选择逻辑：

1. 若传入 adapter，直接使用
2. 若 autoEnv: true，调用 detectEnv() 自动选择
3. 否则默认使用 WebAdapter ⚠️ 小程序环境必须设置 autoEnv: true，否则功能异常

NovaSDK 实例方法

| 方法 | 签名 | 说明 | |------|------|------| | use | (plugin: Plugin) => this | 注册插件 | | request | (url: string, options?: any) => Promise<any> | 发起网络请求（代理适配器） | | getStorage | (key: string) => any | 读取本地存储 | | setStorage | (key: string, value: any) => void | 写入本地存储 | | navigate | (url: string) => void | 页面跳转 | | getEnv | () => string | 获取当前环境标识 |

NovaSDK 实例属性

| 属性 | 类型 | 说明 | |------|------|------| | config | NovaConfig | 初始化配置 |

detectEnv()

检测当前运行环境。

import { detectEnv } from '@bi-nova/core'

const env = detectEnv() // 'web' | 'wechat' | 'alipay' | 'unknown'

检测优先级： wechat > alipay > web > unknown

UMD 使用

通过 <script> 标签引入 UMD 产物后，所有导出挂载在 window.BiNova 上：

<script src="bi-nova.umd.js"></script>
<script>
  const { createNova } = window.BiNova
  const nova = createNova({ appId: 'xxx', autoEnv: true })
</script>

UMD 全局类型声明可通过 @bi-nova/core/global 导入：

/// <reference types="@bi-nova/core/global" />

类型导出

import type {
  AdapterInterface,
  NovaConfig,
  Plugin,
} from '@bi-nova/core'

import type { ComponentBinding, ComponentHandle } from '@bi-nova/core'

故障排查

Q: 小程序中报错 "fetch is not defined" 或 "localStorage is not defined"？

原因： 未设置 autoEnv: true，SDK 默认使用 WebAdapter（依赖 fetch、localStorage 等 Web API），而小程序环境不支持这些 API。

解决方案：

// 方式一：开启自动环境检测（推荐）
const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // 自动选择 WechatAdapter 或 AlipayAdapter
})

// 方式二：手动指定适配器
import { WechatAdapter } from '@bi-nova/core'
const nova = createNova({
  appId: 'your-app-id',
  adapter: new WechatAdapter(),
})

Q: 小程序中网络请求、存储功能不工作？

原因： 同上，使用了错误的适配器。

解决方案： 设置 autoEnv: true 或手动指定对应平台的适配器。

Q: 如何确认当前使用的适配器？

方法： 调用 nova.getEnv() 查看当前环境：

console.log(nova.getEnv()) // 'web' | 'wechat' | 'alipay'

Q: 跨端开发（Taro/uniapp）如何配置？

推荐配置： 设置 autoEnv: true，让 SDK 根据运行环境自动选择适配器：

const nova = createNova({
  appId: 'your-app-id',
  autoEnv: true, // H5 用 WebAdapter，小程序用对应适配器
})