gamelet-pixui-frame/readme.md

pixui开发者框架

# Gamelet PixUI Uniform Frame

### GameletAPI 使用指引

+ 手动引入

```
yarn add gamelet-pixui-frame
```

+ 在代码中引用接口

```
import { GameletAPI } from "gamelet-pixui-frame"
```

---

### 按平台精简体积（子入口用法）

> 如果你**已经明确知道**自己的活动只跑在某一种宿主里（仅 JSSDK / 仅 Unity / 仅 UE），可以使用对应的"子入口"导入，让打包器只把目标平台的实现打进 bundle，避免把另外几套实现也带进去。

#### 我应该选哪个入口？

| 你的场景 | 推荐入口 | 行为 |
|---|---|---|
| 不在意几十 KB 体积，想装上能跑 | `gamelet-pixui-frame`（默认） | 运行时自动判断 5 个平台，含 Unsupported 兜底 |
| 活动只发到 **JSSDK**（含开发态用 PxIDE 调试） | `gamelet-pixui-frame/jssdk` | 只含 JSSDK + PxIDE 实现 |
| 活动只发到 **Pandora Unity**（含 PxIDE 调试） | `gamelet-pixui-frame/unity` | 只含 Unity + PxIDE 实现 |
| 活动只发到 **Pandora UE**（含 PxIDE 调试） | `gamelet-pixui-frame/ue` | 只含 UE + PxIDE 实现 |

> 三个子入口都自带 PxIDE 支持，**不影响你在 PxIDE 里继续调试**。

#### 安装与使用

安装命令完全不变：

```bash
yarn add gamelet-pixui-frame
# 或
npm install gamelet-pixui-frame
```

只需在业务代码里改 `import` 路径：

```ts
// 默认入口（懒人模式，运行时自动判断）
import { GameletAPI } from "gamelet-pixui-frame";

// 仅 JSSDK + PxIDE 调试
import { GameletAPI } from "gamelet-pixui-frame/jssdk";

// 仅 Unity + PxIDE 调试
import { GameletAPI } from "gamelet-pixui-frame/unity";

// 仅 UE + PxIDE 调试
import { GameletAPI } from "gamelet-pixui-frame/ue";
```

子入口下，`GameletAPI` 的接口、类型定义、调用方式与默认入口**完全一致**，业务代码无需做其他改动。

#### 体积收益参考

打包器开启 tree-shaking 后的相对体积（以默认入口为基线，仅供参考，最终以实际打包结果为准）：

| 入口 | 含实现 | 相对默认入口 |
|---|---|---|
| 默认 `gamelet-pixui-frame` | JSSDK + Unity + UE + PxIDE + Unsupported | 100% |
| `gamelet-pixui-frame/jssdk` | JSSDK + PxIDE | 约 60%~70% |
| `gamelet-pixui-frame/unity` | Unity + PxIDE | 约 40%~50% |
| `gamelet-pixui-frame/ue` | UE + PxIDE | 约 40%~50% |

#### 注意事项

1. **fail-fast：选错入口会在启动时直接报错**

   子入口会在 import 阶段检测运行环境，如果与目标平台不匹配，会**立即抛异常**，例如：

   ```text
   [gamelet-pixui-frame/jssdk] 子入口与运行环境不匹配。
   期望: JSSDK 或 PxIDE; 实测 _sdk_info=openplatform_unity;
   请改用 'gamelet-pixui-frame' 默认入口，或检查打包配置是否引错子入口。
   ```

   异常发生在模块加载期，**不能被 try/catch 捕获**，这是有意为之，目的是让"引错入口"的问题第一时间暴露，而不是悄悄降级到 noop。

2. **不要在同一个项目里混用默认入口和子入口**

   `GameletAPI` 是单例。同时 import 默认入口和子入口可能造成"实例分裂"，请二选一。

3. **打包器要求**

   `exports` 子入口需要打包器支持 `package.json` 的 `exports` 字段。webpack 5+ / vite / rollup / esbuild / Node.js 12.7+ 都已默认支持；如果你在用很老的打包器无法解析子入口，请回退到默认入口。


---

### 变更历史

0.5.0（⚠ Breaking Changes）

> 本版本对包入口和内部类做了较大调整，存量用户从默认入口 `gamelet-pixui-frame` 升级**无感知**，但**直接 import 内部实现/构造类**的用户需要注意。

+ 新增按平台精简体积的子入口：`gamelet-pixui-frame/jssdk` / `gamelet-pixui-frame/unity` / `gamelet-pixui-frame/ue`，配合 tree-shaking 可显著减小 bundle 体积，详见上文「按平台精简体积」章节
+ 默认入口 `gamelet-pixui-frame` 行为保持不变（运行时自动判断 5 个平台 + Unsupported 兜底），存量代码无需修改
+ ⚠ **破坏性变更**：`GameletAPIImpl` 构造函数签名由 `()` 改为 `(impl: IGameletAPI, sdkType: RuntimeSDK)`，导出形式由 `singleton instance` 改为裸类导出
  + 影响范围：仅影响**直接 `new GameletAPIImpl()` 或直接 import 该类**的用户；通过 `import { GameletAPI } from 'gamelet-pixui-frame'` 拿到的单例**完全不受影响**
  + 迁移建议：业务代码请始终通过具名 import `GameletAPI` 使用单例，不要自己 `new GameletAPIImpl()`
+ 修复：及时清理 RPC 已 resolve 的回调，修复内存泄漏问题
+ 修复：`getcookiedjc` 通过 holder + setter 注入 `GameletAPI`，解决与 `gameletapi.ts` 的循环依赖

0.4.11

+ 对 UD 的 sAccount 字段做了兼容处理
+ 增加了 `getResourcePath` 接口用于获取资源路径

0.4.10

+ 修改 API 和 SDK 为同步通信
+ 增加 readRoleCookie / writeRoleCookie 接口
+ 优化接口注释

0.4.9 

+ 增加 getAPPInfo 查询接口，传入 appId, appKey , 校验后返回 appVersion, appName, 本接口仅支持 GameletSDK

+ 增加 setAppEnv 接口 允许用户自行设置 App 信息（仅限一个页面中存在多活动在的特殊情况使用），支持 GameletSDK

0.4.8

+ PxIDE 环境下 CanUsePlatformAPI 接口默认返回 false
+ 增加 pluginsForActivityCenter 插件
+ 支持Pandora ueSDK 部分接口
  ```
  GameletAPI.gameCustomFunction()
  GameletAPI.SetDataStash()
  GameletAPI.GetDataStash()
  GameletAPI.ClearDataStash()
  GameletAPI.getUserData()
  ```

0.4.7

+ 更新pxide分支下 getOpenArgs 和 getEntryInfo 返回值改为 "{}"

0.4.6

+ 修复 reportStatsV2 接口在 atm 渠道 goodsId 类型问题,  number->string

0.4.5

+ 修复pandora unity引擎atm上报参数出错的bug

0.4.4（deprecated）

+ 增加了 unity 中 JS 异常的默认 TDM 上报

0.4.3（deprecated）

+ 增加获取引擎版本信息的接口  `getEntryInfo`
+ 增加判断是否支持callbroker的接口 `getIsSupportCallbroker`
+ 在增加获取faas地址的接口 `getFaasAddr`
+ 修复atm接口上报字段

0.4.2

+ 修复 pandoraUnitySDK上 getPlatformDesc 平台判断接口
+ 增加  getIsHitBackendWhitelist 标识是否白名单发布
+ 在白名单发布时支持 close 关闭指定活动的页面
+ reportState 接口暴露 appid 参数

0.4.1

+ 修复 addOnSrvPushDataListener , removeOnSrvPushDataListener 接收服务器推送接口的错误
+ 允许数据虚拟机打开活动页面，但仅在debug打开情况下可用

0.4.0

+ 新增接口
  + 新增 reportStatsV2 统计上报接口，reportMonitorV2 监控上报接口
  + 增加 faas http 上报和日志上报能力
  + 新增 writeCookie, readCookie, deleteCookie 持久化记录接口
  + userdata 中增加 sRegion 字段
+ 支持三方框架
  + 新增DJC  cookie处理接口

0.3.7

+ 修复 Pandora Unity SDK 获取 UD 数据不全的问题

0.3.6

+ 修复 openargs 中不能带=的问题

0.3.5

+ 优化了 Runtime 运行环境的识别方式
  + GameletSDK , PandoraUnitySDK , PxDev 模拟器都可以自动识别
  + 对于旧版本pixui模拟器（VSCode插件中集成的模拟器），可以在URL后手动加参数来设置pxide环境 _sdk_info=openplatform_pxide
  + 请不要用浏览器预览页面，浏览器会被识别为 UNSUPPORT_SDK

0.3.4

+ 修复 userdata 中传入的空字符串会变为 undefined 的问题，让游戏传入和活动获取值保持一致

0.3.3

+ 修复 reportStats， reportToATM 接口中 extendList 参数类型定义

0.3.2

+ 优化接口说明

0.3.1

+ userdata 增加了 sLanguage 字段
+ 优化了 unity 环境下 setGameletAppEnv, 根据传入 appId 或者 appName, 如果用户命中了此活动，则未填写的app信息自动补齐

0.3.0

+ userdata 增加了 sIntlSdkParam 字段。
+ 重写 console.log 让活动默认输出 appId。console.error 错误日志中增加了堆栈。

0.2.11

+ userdata 中增加了 sCountry 和 sLoginChannel 字段