mini-three-adapter 0.1.7 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +85 -85
- package/LICENSE +21 -21
- package/README.md +159 -159
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-HKT54DDM.js → chunk-DQH3YRGN.js} +3 -3
- package/dist/chunk-DQH3YRGN.js.map +1 -0
- package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
- package/dist/chunk-J34MD3IL.js.map +1 -0
- package/dist/{chunk-U3P3XHA3.js → chunk-LAVHSWBU.js} +2 -2
- package/dist/{chunk-U3P3XHA3.js.map → chunk-LAVHSWBU.js.map} +1 -1
- package/dist/{chunk-7XOHQFZ6.js → chunk-RYWYBOYO.js} +4 -4
- package/dist/chunk-RYWYBOYO.js.map +1 -0
- package/dist/{chunk-DDCQIBWW.js → chunk-SXQUZI22.js} +4 -4
- package/dist/chunk-SXQUZI22.js.map +1 -0
- package/dist/{chunk-V64V4HIZ.js → chunk-TPMMZFHW.js} +22 -6
- package/dist/chunk-TPMMZFHW.js.map +1 -0
- package/dist/{chunk-FQ2GOIOE.js → chunk-YPG3QUYK.js} +4 -4
- package/dist/chunk-YPG3QUYK.js.map +1 -0
- package/dist/core/index.js +3 -3
- package/dist/index.js +7 -7
- package/dist/platforms/browser.js +4 -4
- package/dist/platforms/wechat-game.js +5 -5
- package/dist/platforms/wechat-miniprogram.js +5 -5
- package/dist/polyfills/index.js +1 -1
- package/dist/scope.js +1 -1
- package/docs/01-design-principles.md +105 -105
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +310 -310
- package/docs/05-build-plugin.md +176 -176
- package/docs/06-platform-notes.md +6 -3
- package/docs/07-integration-guide.md +226 -226
- package/docs/08-extension-guide.md +101 -101
- package/docs/09-testing-and-release.md +212 -212
- package/docs/11-compat-matrix.md +100 -100
- package/docs/README.md +41 -41
- package/docs/adr/0001-scoped-globals.md +41 -41
- package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
- package/docs/adr/0003-ast-rewrite.md +51 -51
- package/docs/adr/0004-in-place-patching.md +42 -42
- package/docs/adr/0005-webgl2-only.md +44 -44
- package/docs/adr/0006-zero-three-dependency.md +43 -43
- package/docs/adr/0007-capability-probe-fallback.md +61 -61
- package/docs/adr/0008-probe-fallback-boundary.md +56 -56
- package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
- package/docs/adr/0010-native-event-target-boundary.md +82 -82
- package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
- package/docs/adr/README.md +33 -32
- package/package.json +126 -126
- package/dist/chunk-35XVAVDB.js.map +0 -1
- package/dist/chunk-7XOHQFZ6.js.map +0 -1
- package/dist/chunk-DDCQIBWW.js.map +0 -1
- package/dist/chunk-FQ2GOIOE.js.map +0 -1
- package/dist/chunk-HKT54DDM.js.map +0 -1
- package/dist/chunk-V64V4HIZ.js.map +0 -1
package/docs/04-api-reference.md
CHANGED
|
@@ -1,310 +1,310 @@
|
|
|
1
|
-
# 04 · API 参考
|
|
2
|
-
|
|
3
|
-
> 版本:0.1.6。所有签名以 `src/**` 与 `npm run build` 生成的 `dist/*.d.ts` 为准。
|
|
4
|
-
> 子路径导入可最大化 tree-shaking;`mini-three-adapter` 是汇总入口。
|
|
5
|
-
|
|
6
|
-
## 4.1 子路径
|
|
7
|
-
|
|
8
|
-
| 子路径 | 内容 |
|
|
9
|
-
| --- | --- |
|
|
10
|
-
| `mini-three-adapter` | 全部公开 API |
|
|
11
|
-
| `mini-three-adapter/core` | 平台无关运行时 |
|
|
12
|
-
| `mini-three-adapter/scope` | `getActiveScope()` 等(**构建插件注入的 import 目标**) |
|
|
13
|
-
| `mini-three-adapter/wechat-game` | 小游戏入口 |
|
|
14
|
-
| `mini-three-adapter/wechat-miniprogram` | 小程序入口 |
|
|
15
|
-
| `mini-three-adapter/browser` | 浏览器 / H5 / Node 测试 |
|
|
16
|
-
| `mini-three-adapter/polyfills` | 独立 polyfill |
|
|
17
|
-
| `mini-three-adapter/vite` | Vite 插件 |
|
|
18
|
-
| `mini-three-adapter/rollup` | Rollup 插件 + 高级 API |
|
|
19
|
-
| `mini-three-adapter/plugin` | `vite` 的别名 |
|
|
20
|
-
| `mini-three-adapter/package.json` | 读取包元信息(`version`、`exports`) |
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## 4.2 生命周期
|
|
25
|
-
|
|
26
|
-
### `createRuntime(platform, options?) => Promise<MiniThreeRuntime>`
|
|
27
|
-
|
|
28
|
-
平台无关的总装配入口。通常不直接调用,而用下面的平台快捷函数。
|
|
29
|
-
|
|
30
|
-
```ts
|
|
31
|
-
function createRuntime(
|
|
32
|
-
platform: PlatformBinding | PlatformFactory,
|
|
33
|
-
options?: RuntimeOptions,
|
|
34
|
-
): Promise<MiniThreeRuntime>;
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
### `createWeChatGameRuntime(options?) => Promise<MiniThreeRuntime>`
|
|
38
|
-
|
|
39
|
-
```ts
|
|
40
|
-
interface WeChatGameOptions {
|
|
41
|
-
wx?: WxLike; // 注入 wx(测试/非微信宿主)
|
|
42
|
-
canvas?: WxCanvas; // 复用已有上屏画布
|
|
43
|
-
capabilities?: Partial<Capabilities>;
|
|
44
|
-
diagnostics?: Diagnostics;
|
|
45
|
-
preferredFps?: number; // wx.setPreferredFramesPerSecond
|
|
46
|
-
}
|
|
47
|
-
type WeChatGameRuntimeOptions = WeChatGameOptions & RuntimeOptions;
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
另有 `createWeChatGameBinding(options) => PlatformBinding`(同步)、`getScreenCanvas(wx, supplied?)`、`resetScreenCanvasCache()`(测试用)。
|
|
51
|
-
|
|
52
|
-
### `createWeChatMiniProgramRuntime(options) => Promise<MiniThreeRuntime>`
|
|
53
|
-
|
|
54
|
-
```ts
|
|
55
|
-
interface WeChatMiniProgramOptions {
|
|
56
|
-
wx?: WxLike;
|
|
57
|
-
selector: string; // 例如 '#gl'
|
|
58
|
-
selectorCtx?: SelectorCtx; // 自定义组件内传 this
|
|
59
|
-
queryDelay?: number; // 等待布局的毫秒数
|
|
60
|
-
capabilities?: Partial<Capabilities>;
|
|
61
|
-
diagnostics?: Diagnostics;
|
|
62
|
-
}
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
另有 `createWeChatMiniProgramBinding(options) => Promise<PlatformBinding>`。
|
|
66
|
-
|
|
67
|
-
### `createBrowserRuntime(options?) => Promise<MiniThreeRuntime>`
|
|
68
|
-
|
|
69
|
-
```ts
|
|
70
|
-
interface BrowserPlatformOptions {
|
|
71
|
-
canvas?: HTMLCanvasElement;
|
|
72
|
-
capabilities?: Partial<Capabilities>;
|
|
73
|
-
diagnostics?: Diagnostics;
|
|
74
|
-
}
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
---
|
|
78
|
-
|
|
79
|
-
### `RuntimeOptions`
|
|
80
|
-
|
|
81
|
-
| 选项 | 类型 | 默认 | 说明 |
|
|
82
|
-
| --- | --- | --- | --- |
|
|
83
|
-
| `pixelRatioCap` | `number` | `2` | 限制 DPR,`0` 表示不封顶 |
|
|
84
|
-
| `propagatePointerEvents` | `boolean` | `true` | 是否同时派发到 `document` / `window` |
|
|
85
|
-
| `emitMouseEvents` | `boolean` | `true` | 是否额外发 `mouse*` / `click` |
|
|
86
|
-
| `defaultContextType` | `'webgl2' \| 'webgl' \| '2d'` | `'webgl2'` | `document.createElement('canvas')` 的默认上下文 |
|
|
87
|
-
| `cacheContexts` | `boolean` | `true` | 缓存 `getContext()` 结果,保证上下文身份稳定 |
|
|
88
|
-
| `normalizeWebGL` | `boolean` | `true` | 修正 `getExtension` 返回值、`drawingBufferWidth/Height` |
|
|
89
|
-
| `fpsCap` | `number` | `0` | 逻辑帧率上限 |
|
|
90
|
-
| `slowFrameThreshold` | `number` | `0` | 慢帧告警阈值(ms) |
|
|
91
|
-
| `logLevel` | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | 日志级别 |
|
|
92
|
-
| `reporter` | `Reporter` | console | 自定义日志出口 |
|
|
93
|
-
| `capabilities` | `Partial<Capabilities>` | — | 覆盖探测结果 |
|
|
94
|
-
| `installGlobals` | `boolean` | `false` | 启动时立即注入全局(可逆) |
|
|
95
|
-
| `diagnostics` | `Diagnostics` | — | 平台层注入(平台 options) |
|
|
96
|
-
|
|
97
|
-
### `MiniThreeRuntime`
|
|
98
|
-
|
|
99
|
-
| 成员 | 类型 | 说明 |
|
|
100
|
-
| --- | --- | --- |
|
|
101
|
-
| `canvas` | `HTMLCanvasElement` | 已就地补丁的上屏/节点画布 |
|
|
102
|
-
| `scope` | `MiniThreeScope` | 三方代码可见的作用域对象 |
|
|
103
|
-
| `document` | `DocumentLike` | `createElement` / `createElementNS` / `body` / `defaultView` |
|
|
104
|
-
| `capabilities` | `Capabilities` | 探测结果 |
|
|
105
|
-
| `diagnostics` | `Diagnostics` | 日志与报告 |
|
|
106
|
-
| `frames` | `FrameScheduler` | rAF / delta / fps |
|
|
107
|
-
| `bridge` | `PointerBridge` | 事件桥 |
|
|
108
|
-
| `windowInfo` | `WindowInfo` | 实时尺寸与 DPR(getter) |
|
|
109
|
-
| `rendererHints` | `RendererHints` | 可直接展开给 `new THREE.WebGLRenderer()` |
|
|
110
|
-
| `disposed` | `boolean` | 是否已释放 |
|
|
111
|
-
| `handleTouch(event, opts?)` | `(TouchLikeEvent, {propagate?, computeRect?}) => void` | 手动转发触摸(小程序必需) |
|
|
112
|
-
| `resize()` | `() => Promise<void>` | 重新测量并广播 resize |
|
|
113
|
-
| `installGlobals(opts?)` | `() => Disposer` | 显式全局注入并返回还原函数 |
|
|
114
|
-
| `createCanvas(w?, h?, type?)` | `() => HTMLCanvasElement` | 额外的离屏画布 |
|
|
115
|
-
| `on(event, listener)` | `() => Disposer` | 见下表 |
|
|
116
|
-
| `report()` | `() => string` | 能力报告文本 |
|
|
117
|
-
| `dispose()` | `() => void` | 释放全部副作用 |
|
|
118
|
-
|
|
119
|
-
`RuntimeEvents`:
|
|
120
|
-
|
|
121
|
-
| 事件 | 回调 |
|
|
122
|
-
| --- | --- |
|
|
123
|
-
| `resize` | `(info: WindowInfo) => void` |
|
|
124
|
-
| `visibilitychange` | `(visible: boolean) => void` |
|
|
125
|
-
| `contextlost` | `() => void` |
|
|
126
|
-
| `dispose` | `() => void` |
|
|
127
|
-
| `error` | `(error: Error) => void` |
|
|
128
|
-
|
|
129
|
-
`RendererHints`:`{ canvas, antialias: false, alpha: false, powerPreference: 'high-performance', preserveDrawingBuffer: false, outputColorSpace: 'srgb' }`。
|
|
130
|
-
|
|
131
|
-
---
|
|
132
|
-
|
|
133
|
-
## 4.3 作用域
|
|
134
|
-
|
|
135
|
-
```ts
|
|
136
|
-
function createScope(overrides?: Partial<MiniThreeScope>): MiniThreeScope;
|
|
137
|
-
function getActiveScope(): MiniThreeScope; // 未初始化时返回占位对象,见下
|
|
138
|
-
function setActiveScope(scope: MiniThreeScope | null): () => void;
|
|
139
|
-
function hasActiveScope(): boolean;
|
|
140
|
-
function installGlobals(scope, options?): () => void;
|
|
141
|
-
function getEarlyScopeReads(): readonly string[]; // 未初始化时被读过的全局名
|
|
142
|
-
function clearEarlyScopeReads(): void;
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
未初始化时的占位对象有两条不同策略:
|
|
146
|
-
|
|
147
|
-
- `window` / `self` / `globalThis` 指向自身,`typeof window === 'object'`,与 three 的特性检测假设一致;
|
|
148
|
-
- `document` / `navigator` / `screen` / `location` / `history` 读作 `undefined`,等价于「这个宿主没有 DOM」。`typeof` 对这些键永不抛错,包括构建插件无法守卫的 `typeof window.document` 形态;
|
|
149
|
-
- 其余键(`HTMLCanvasElement`、`TextDecoder`、`Blob` …)读取即抛错,因为那不是探测而是真实使用,静默 `undefined` 只会在几帧之后以无关的形式爆掉。
|
|
150
|
-
|
|
151
|
-
这些「读作 `undefined`」的早读会被记录,`createRuntime()` 启动后 `warnOnce` 汇总一次(提示 `three` 求值过早),随后清空。
|
|
152
|
-
|
|
153
|
-
`MiniThreeScope` 同时扮演 `window` / `self` / `globalThis`(三者指向自身),并包含:
|
|
154
|
-
|
|
155
|
-
- 领域对象:`document`、`navigator`、`screen`、`performance`、`getComputedStyle`、`matchMedia`;
|
|
156
|
-
- 尺寸:`innerWidth`、`innerHeight`、`outerWidth`、`outerHeight`、`devicePixelRatio`、`pageXOffset`、`pageYOffset`(均为 live getter);
|
|
157
|
-
- 事件:`Event`、`EventTarget`、`CustomEvent`、`PointerEvent`、`MouseEvent`、`TouchEvent`、`MessageEvent`、`ProgressEvent`、`KeyboardEvent`、`DOMException`;
|
|
158
|
-
- DOM:`HTMLElement`、`HTMLCanvasElement`、`HTMLImageElement`、`OffscreenCanvas`、`Image`、`ImageData`、`DOMRect`、`WebGLRenderingContext`、`WebGL2RenderingContext`、`AudioContext`;
|
|
159
|
-
- 网络/编码:`Blob`、`URL`、`TextEncoder`、`TextDecoder`、`fetch`、`XMLHttpRequest`、`AbortController`、`AbortSignal`、`atob`、`btoa`;
|
|
160
|
-
- 帧:`requestAnimationFrame`、`cancelAnimationFrame`;
|
|
161
|
-
- 明确不可用:`createImageBitmap`、`FileReader`、`WebSocket` 为 `undefined`(让 three 走降级分支)。
|
|
162
|
-
|
|
163
|
-
`installGlobals(scope, { target?, skipExisting?, extraKeys? })` 把上述键定义为 `globalThis` 上的 getter;返回的 disposer 会精确还原原有 descriptor。
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## 4.4 core 子路径
|
|
168
|
-
|
|
169
|
-
| API | 签名 / 说明 |
|
|
170
|
-
| --- | --- |
|
|
171
|
-
| `patchElement(instance, options)` | 就地补 DOM 属性,返回 `{ element, updateRect, disposers }`。`options.nativeEventTarget: true` 表示目标自带原生事件系统:跳过 `patchEventTarget`,且只补**缺失**的成员(`style` / `getBoundingClientRect` / `setPointerCapture` 等留给宿主),见 [ADR-0010](./adr/0010-native-event-target-boundary.md) |
|
|
172
|
-
| `createMockClass(name)` | 生成带 `Symbol.hasInstance` + `WeakSet` 的构造器 shim |
|
|
173
|
-
| `markAs(ctor, obj)` / `isMarked(ctor, obj)` | 注册 / 查询 instanceof 关系 |
|
|
174
|
-
| `*Shim` | `HTMLCanvasElementShim`、`HTMLImageElementShim`、`HTMLElementShim`、`OffscreenCanvasShim`、`ImageDataShim`、`WebGLRenderingContextShim`、`WebGL2RenderingContextShim`、`DOMRectShim` |
|
|
175
|
-
| `patchCanvas(raw, options)` | 返回 `{ canvas, contexts, updateRect, element, disposers }`。`nativeEventTarget` 透传给 `patchElement`;无论哪种模式都接管 `getContext`(上下文缓存 + WebGL 归一化) |
|
|
176
|
-
| `createOffscreenCanvas(wx, w?, h?, options?)` | 直接创建并补丁离屏画布 |
|
|
177
|
-
| `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }`。工厂按「原生 `addEventListener` → `onload`/`onerror` 赋值 → `wx.getImageInfo` → 2s watchdog」四级兜底把宿主事件桥接成合成事件:`img.onload = fn` 与 `addEventListener('load', fn)` 都能收到通知,`complete` 在成功/失败后都为 `true`,`decode()` 据此 resolve/reject。watchdog 对所有宿主无条件生效:`src` 赋值后 2s 内没有真实事件时,`complete` 为真则派发 `load`,否则派发带 `reason` 的 `error
|
|
178
|
-
| `createDocument(options)` / `createScreen(w, h)` / `ShimDOMRect` | 伪 DOM 容器 |
|
|
179
|
-
| `PointerBridge` | `dispatch(event, opts?)`、`dispatchMouse(event)`、`setRect`、`refreshRect`、`setPointerCapture`、`releasePointerCapture`、`activePointerCount`、`dispose`。构造选项 `createEvent(type, init)` 存在时派发**真实 DOM 事件**而不是 `MiniEvent`;`nativeEventTarget: true` 时不再向 `document` / `window` 转派(浏览器自己冒泡),见 [ADR-0010](./adr/0010-native-event-target-boundary.md) |
|
|
180
|
-
| `createFrameScheduler(raf, caf, options)` | `request` / `cancel` / `loop(cb)` / `setFpsCap` / `fps` / `dispose` |
|
|
181
|
-
| `createWindowInfoStore(wx, options)` | `info` / `refresh()` / `onChange()` / `setPixelRatioCap()` / `dispose()` |
|
|
182
|
-
| `detectCapabilities(wx, platform, options)` / `versionAtLeast(a, b)` | 能力探测。`options.probeContext(type)` 返回 `true` / `false` / `undefined`,**`undefined` 表示「探测不到」而不是「不支持」**,此时 `webgl2` 按基础库版本推断并在 `webgl2Source` 里标记为 `'inferred'` |
|
|
183
|
-
| `createDiagnostics(level, reporter)` / `capabilityReport(caps)` | 日志与报告 |
|
|
184
|
-
| `currentScope()` | 返回当前作用域或 `null` |
|
|
185
|
-
|
|
186
|
-
### `PlatformBinding`(新增平台时实现)
|
|
187
|
-
|
|
188
|
-
```ts
|
|
189
|
-
interface PlatformBinding {
|
|
190
|
-
readonly kind: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
|
|
191
|
-
readonly wx?: WxLike;
|
|
192
|
-
readonly rawCanvas: WxCanvas;
|
|
193
|
-
readonly capabilities: Capabilities;
|
|
194
|
-
readonly imageFactory: ImageFactory;
|
|
195
|
-
/** true = rawCanvas 自带原生事件系统(浏览器)。缺省 false(微信裸对象)。 */
|
|
196
|
-
readonly nativeEventTarget?: boolean;
|
|
197
|
-
/** nativeEventTarget 为真时构造真实 DOM 事件。 */
|
|
198
|
-
createEvent?(type: string, init: NativeEventInit): unknown;
|
|
199
|
-
getCanvasRect(): Rect | Promise<Rect>;
|
|
200
|
-
createOffscreenCanvas(w: number, h: number, type: ContextType): WxCanvas;
|
|
201
|
-
watchTouch(handler: (e: TouchLikeEvent) => void): Disposer;
|
|
202
|
-
watchVisibility(handler: (visible: boolean) => void): Disposer;
|
|
203
|
-
requestAnimationFrame(cb: (time: number) => void): number;
|
|
204
|
-
cancelAnimationFrame(id: number): void;
|
|
205
|
-
now(): number;
|
|
206
|
-
dispose(): void;
|
|
207
|
-
}
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
`nativeEventTarget` 决定的是**归属**而不是能力:为真时 `addEventListener` / `dispatchEvent` / `style` / `getBoundingClientRect` 全部留给宿主,适配层只在缺失时补;为假时按 [ADR-0004](./adr/0004-in-place-patching.md) 用 `MiniEventTarget` 接管。自己实现新平台时,如果宿主是裸对象(小程序、小游戏、原生渲染层)就保持缺省;只有目标本身就是标准 DOM 元素时才置真。
|
|
211
|
-
|
|
212
|
-
---
|
|
213
|
-
|
|
214
|
-
## 4.5 polyfills 子路径
|
|
215
|
-
|
|
216
|
-
| API | 说明 |
|
|
217
|
-
| --- | --- |
|
|
218
|
-
| `MiniEvent` / `MiniCustomEvent` / `MiniPointerEvent` / `MiniMouseEvent` / `MiniMessageEvent` / `MiniProgressEvent` / `MiniDOMException` | 事件对象 |
|
|
219
|
-
| `MiniEventTarget` / `patchEventTarget(obj)` | 事件目标;`patchEventTarget` 不改变对象身份。监听器被调用时 `this`、`event.target`、`event.currentTarget` 都是**宿主元素**而不是内部载体——three 的 `ImageLoader` 用 `this` 取 `<img>` 当纹理源,拿错对象就等于没有像素。`dispatchEvent()` 只对 `MiniEvent` 实例写 `target` / `currentTarget`:真实 DOM `Event` 的这两个字段是只读访问器,写入会在严格模式下抛错(见 ADR-0010) |
|
|
220
|
-
| `MiniBlob` | `bytes()`、`arrayBuffer()`、`text()`、`slice()`、`dataURL()`、`size`、`type` |
|
|
221
|
-
| `MiniURL` | `createObjectURL` / `revokeObjectURL` / `resolveObjectURL` / `clearObjectURLs`;构造器支持相对路径解析 |
|
|
222
|
-
| `MiniURLSearchParams` | `get` / `set` / `toString` |
|
|
223
|
-
| `bytesToBase64` / `base64ToBytes` / `resolveUrl` | 编码与 URL 工具 |
|
|
224
|
-
| `atob` / `btoa` / `MiniTextEncoder` / `MiniTextDecoder` | 编码 |
|
|
225
|
-
| `createFetch(wx)` / `MiniXMLHttpRequest` / `createXMLHttpRequestFactory(wx)` / `MiniAbortController` / `MiniAbortSignal` | 网络 |
|
|
226
|
-
|
|
227
|
-
> 注意:对象 URL 采用 `mini-three-blob:` 前缀并解析为 `data:` URI,而不是浏览器 `blob:` ——因为微信 image loader 只认 `data:` / 本地路径。
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## 4.6 构建插件
|
|
232
|
-
|
|
233
|
-
### Vite
|
|
234
|
-
|
|
235
|
-
```ts
|
|
236
|
-
import miniThree from 'mini-three-adapter/vite';
|
|
237
|
-
plugins: [miniThree(options)];
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
插件额外提供 `config()`,设置 `optimizeDeps.exclude: ['three', 'three-stdlib', 'three/examples/jsm']`,确保 AST 重写见到原始 ESM 模块图。
|
|
241
|
-
|
|
242
|
-
### Rollup
|
|
243
|
-
|
|
244
|
-
```ts
|
|
245
|
-
import { miniThree } from 'mini-three-adapter/rollup';
|
|
246
|
-
plugins: [miniThree(options)];
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
### `MiniThreePluginOptions`
|
|
250
|
-
|
|
251
|
-
| 选项 | 类型 | 默认 | 说明 |
|
|
252
|
-
| --- | --- | --- | --- |
|
|
253
|
-
| `include` | `(id: string) => boolean` | 匹配 `three` / `three-stdlib` / `@react-three` / `@tresjs` / `.vite/deps/three*` | 需要重写的模块 |
|
|
254
|
-
| `exclude` | `(id: string) => boolean` | `() => false` | 排除 |
|
|
255
|
-
| `includeUserCode` | `boolean` | `false` | 是否也改写应用代码 |
|
|
256
|
-
| `rewrite` | `RewriteOptions` | — | 高级重写配置 |
|
|
257
|
-
| `webgpu` | `'warn' \| 'error' \| 'rewrite' \| 'ignore'` | `'warn'` | 遇到 `three/webgpu` 的策略 |
|
|
258
|
-
| `roots` | `string[]` | three jsm/libs、`three-stdlib`、`public`、`static` | 资源搜索目录 |
|
|
259
|
-
| `outputDir` | `string` | `'assets/three'` | 资源输出目录 |
|
|
260
|
-
| `brotli` | `boolean` | `true` | 同时拷贝 `.wasm.br` |
|
|
261
|
-
| `manifest` | `boolean` | `true` | 输出 `mini-three-assets.json` |
|
|
262
|
-
| `cwd` | `string` | `process.cwd()` | 解析 roots 的根目录 |
|
|
263
|
-
| `report` | `boolean` | `true` | 打印构建摘要 |
|
|
264
|
-
| `debug` | `boolean` | `false` | 逐模块日志 |
|
|
265
|
-
|
|
266
|
-
### `RewriteOptions`
|
|
267
|
-
|
|
268
|
-
| 选项 | 默认 | 说明 |
|
|
269
|
-
| --- | --- | --- |
|
|
270
|
-
| `globals` | `DEFAULT_GLOBAL_NAMES` | 替换默认清单(而非追加) |
|
|
271
|
-
| `extraGlobals` | `[]` | 追加清单 |
|
|
272
|
-
| `forceUndef` | `['createImageBitmap']` | 强制走 `__m3().x`(作用域中恒为 `undefined`) |
|
|
273
|
-
| `accessor` | `'__m3'` | 注入的 `getActiveScope` 别名 |
|
|
274
|
-
| `scopeModule` | `'mini-three-adapter/scope'` | 注入的 import 路径 |
|
|
275
|
-
|
|
276
|
-
### 高级导出(`mini-three-adapter/rollup`)
|
|
277
|
-
|
|
278
|
-
`rewriteGlobals(code, id, options)`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF`、`collectAssetReferences`、`collectAssets`、`copyAssets`、`miniThreePlugin`。
|
|
279
|
-
|
|
280
|
-
`plugin.api.report()` → `BuildReport`:`modulesScanned`、`modulesRewritten`、`rewrites`、`globalsSeen`、`assetReferences`、`missingAssets`、`webgpuWarnings`、`parseFailures`。
|
|
281
|
-
|
|
282
|
-
---
|
|
283
|
-
|
|
284
|
-
## 4.7 类型速查
|
|
285
|
-
|
|
286
|
-
```ts
|
|
287
|
-
interface Capabilities {
|
|
288
|
-
platform: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
|
|
289
|
-
webgl2: boolean;
|
|
290
|
-
/** 'probe' 实测 / 'inferred' 版本推断 / 'override' 调用方覆盖 */
|
|
291
|
-
webgl2Source?: 'probe' | 'inferred' | 'override';
|
|
292
|
-
webgl1: boolean; offscreenCanvas: boolean;
|
|
293
|
-
worker: boolean; wasm: boolean; brotliWasm: boolean; nativeImage: boolean;
|
|
294
|
-
triggerGC: boolean; getWindowInfo: boolean; windowResizeEvent: boolean;
|
|
295
|
-
baseLibraryVersion: string;
|
|
296
|
-
}
|
|
297
|
-
|
|
298
|
-
interface WindowInfo {
|
|
299
|
-
width: number; height: number; pixelRatio: number; rawPixelRatio: number;
|
|
300
|
-
safeArea?: Rect;
|
|
301
|
-
}
|
|
302
|
-
|
|
303
|
-
interface Rect { top: number; left: number; width: number; height: number; right: number; bottom: number; }
|
|
304
|
-
|
|
305
|
-
interface TouchLikeEvent {
|
|
306
|
-
type: string; touches?: ArrayLike<TouchPoint>;
|
|
307
|
-
changedTouches?: ArrayLike<TouchPoint>; timeStamp?: number;
|
|
308
|
-
[key: string]: unknown;
|
|
309
|
-
}
|
|
310
|
-
```
|
|
1
|
+
# 04 · API 参考
|
|
2
|
+
|
|
3
|
+
> 版本:0.1.6。所有签名以 `src/**` 与 `npm run build` 生成的 `dist/*.d.ts` 为准。
|
|
4
|
+
> 子路径导入可最大化 tree-shaking;`mini-three-adapter` 是汇总入口。
|
|
5
|
+
|
|
6
|
+
## 4.1 子路径
|
|
7
|
+
|
|
8
|
+
| 子路径 | 内容 |
|
|
9
|
+
| --- | --- |
|
|
10
|
+
| `mini-three-adapter` | 全部公开 API |
|
|
11
|
+
| `mini-three-adapter/core` | 平台无关运行时 |
|
|
12
|
+
| `mini-three-adapter/scope` | `getActiveScope()` 等(**构建插件注入的 import 目标**) |
|
|
13
|
+
| `mini-three-adapter/wechat-game` | 小游戏入口 |
|
|
14
|
+
| `mini-three-adapter/wechat-miniprogram` | 小程序入口 |
|
|
15
|
+
| `mini-three-adapter/browser` | 浏览器 / H5 / Node 测试 |
|
|
16
|
+
| `mini-three-adapter/polyfills` | 独立 polyfill |
|
|
17
|
+
| `mini-three-adapter/vite` | Vite 插件 |
|
|
18
|
+
| `mini-three-adapter/rollup` | Rollup 插件 + 高级 API |
|
|
19
|
+
| `mini-three-adapter/plugin` | `vite` 的别名 |
|
|
20
|
+
| `mini-three-adapter/package.json` | 读取包元信息(`version`、`exports`) |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 4.2 生命周期
|
|
25
|
+
|
|
26
|
+
### `createRuntime(platform, options?) => Promise<MiniThreeRuntime>`
|
|
27
|
+
|
|
28
|
+
平台无关的总装配入口。通常不直接调用,而用下面的平台快捷函数。
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
function createRuntime(
|
|
32
|
+
platform: PlatformBinding | PlatformFactory,
|
|
33
|
+
options?: RuntimeOptions,
|
|
34
|
+
): Promise<MiniThreeRuntime>;
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### `createWeChatGameRuntime(options?) => Promise<MiniThreeRuntime>`
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
interface WeChatGameOptions {
|
|
41
|
+
wx?: WxLike; // 注入 wx(测试/非微信宿主)
|
|
42
|
+
canvas?: WxCanvas; // 复用已有上屏画布
|
|
43
|
+
capabilities?: Partial<Capabilities>;
|
|
44
|
+
diagnostics?: Diagnostics;
|
|
45
|
+
preferredFps?: number; // wx.setPreferredFramesPerSecond
|
|
46
|
+
}
|
|
47
|
+
type WeChatGameRuntimeOptions = WeChatGameOptions & RuntimeOptions;
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
另有 `createWeChatGameBinding(options) => PlatformBinding`(同步)、`getScreenCanvas(wx, supplied?)`、`resetScreenCanvasCache()`(测试用)。
|
|
51
|
+
|
|
52
|
+
### `createWeChatMiniProgramRuntime(options) => Promise<MiniThreeRuntime>`
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
interface WeChatMiniProgramOptions {
|
|
56
|
+
wx?: WxLike;
|
|
57
|
+
selector: string; // 例如 '#gl'
|
|
58
|
+
selectorCtx?: SelectorCtx; // 自定义组件内传 this
|
|
59
|
+
queryDelay?: number; // 等待布局的毫秒数
|
|
60
|
+
capabilities?: Partial<Capabilities>;
|
|
61
|
+
diagnostics?: Diagnostics;
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
另有 `createWeChatMiniProgramBinding(options) => Promise<PlatformBinding>`。
|
|
66
|
+
|
|
67
|
+
### `createBrowserRuntime(options?) => Promise<MiniThreeRuntime>`
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
interface BrowserPlatformOptions {
|
|
71
|
+
canvas?: HTMLCanvasElement;
|
|
72
|
+
capabilities?: Partial<Capabilities>;
|
|
73
|
+
diagnostics?: Diagnostics;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
### `RuntimeOptions`
|
|
80
|
+
|
|
81
|
+
| 选项 | 类型 | 默认 | 说明 |
|
|
82
|
+
| --- | --- | --- | --- |
|
|
83
|
+
| `pixelRatioCap` | `number` | `2` | 限制 DPR,`0` 表示不封顶 |
|
|
84
|
+
| `propagatePointerEvents` | `boolean` | `true` | 是否同时派发到 `document` / `window` |
|
|
85
|
+
| `emitMouseEvents` | `boolean` | `true` | 是否额外发 `mouse*` / `click` |
|
|
86
|
+
| `defaultContextType` | `'webgl2' \| 'webgl' \| '2d'` | `'webgl2'` | `document.createElement('canvas')` 的默认上下文 |
|
|
87
|
+
| `cacheContexts` | `boolean` | `true` | 缓存 `getContext()` 结果,保证上下文身份稳定 |
|
|
88
|
+
| `normalizeWebGL` | `boolean` | `true` | 修正 `getExtension` 返回值、`drawingBufferWidth/Height` |
|
|
89
|
+
| `fpsCap` | `number` | `0` | 逻辑帧率上限 |
|
|
90
|
+
| `slowFrameThreshold` | `number` | `0` | 慢帧告警阈值(ms) |
|
|
91
|
+
| `logLevel` | `'silent' \| 'error' \| 'warn' \| 'info' \| 'debug'` | `'warn'` | 日志级别 |
|
|
92
|
+
| `reporter` | `Reporter` | console | 自定义日志出口 |
|
|
93
|
+
| `capabilities` | `Partial<Capabilities>` | — | 覆盖探测结果 |
|
|
94
|
+
| `installGlobals` | `boolean` | `false` | 启动时立即注入全局(可逆) |
|
|
95
|
+
| `diagnostics` | `Diagnostics` | — | 平台层注入(平台 options) |
|
|
96
|
+
|
|
97
|
+
### `MiniThreeRuntime`
|
|
98
|
+
|
|
99
|
+
| 成员 | 类型 | 说明 |
|
|
100
|
+
| --- | --- | --- |
|
|
101
|
+
| `canvas` | `HTMLCanvasElement` | 已就地补丁的上屏/节点画布 |
|
|
102
|
+
| `scope` | `MiniThreeScope` | 三方代码可见的作用域对象 |
|
|
103
|
+
| `document` | `DocumentLike` | `createElement` / `createElementNS` / `body` / `defaultView` |
|
|
104
|
+
| `capabilities` | `Capabilities` | 探测结果 |
|
|
105
|
+
| `diagnostics` | `Diagnostics` | 日志与报告 |
|
|
106
|
+
| `frames` | `FrameScheduler` | rAF / delta / fps |
|
|
107
|
+
| `bridge` | `PointerBridge` | 事件桥 |
|
|
108
|
+
| `windowInfo` | `WindowInfo` | 实时尺寸与 DPR(getter) |
|
|
109
|
+
| `rendererHints` | `RendererHints` | 可直接展开给 `new THREE.WebGLRenderer()` |
|
|
110
|
+
| `disposed` | `boolean` | 是否已释放 |
|
|
111
|
+
| `handleTouch(event, opts?)` | `(TouchLikeEvent, {propagate?, computeRect?}) => void` | 手动转发触摸(小程序必需) |
|
|
112
|
+
| `resize()` | `() => Promise<void>` | 重新测量并广播 resize |
|
|
113
|
+
| `installGlobals(opts?)` | `() => Disposer` | 显式全局注入并返回还原函数 |
|
|
114
|
+
| `createCanvas(w?, h?, type?)` | `() => HTMLCanvasElement` | 额外的离屏画布 |
|
|
115
|
+
| `on(event, listener)` | `() => Disposer` | 见下表 |
|
|
116
|
+
| `report()` | `() => string` | 能力报告文本 |
|
|
117
|
+
| `dispose()` | `() => void` | 释放全部副作用 |
|
|
118
|
+
|
|
119
|
+
`RuntimeEvents`:
|
|
120
|
+
|
|
121
|
+
| 事件 | 回调 |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `resize` | `(info: WindowInfo) => void` |
|
|
124
|
+
| `visibilitychange` | `(visible: boolean) => void` |
|
|
125
|
+
| `contextlost` | `() => void` |
|
|
126
|
+
| `dispose` | `() => void` |
|
|
127
|
+
| `error` | `(error: Error) => void` |
|
|
128
|
+
|
|
129
|
+
`RendererHints`:`{ canvas, antialias: false, alpha: false, powerPreference: 'high-performance', preserveDrawingBuffer: false, outputColorSpace: 'srgb' }`。
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 4.3 作用域
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
function createScope(overrides?: Partial<MiniThreeScope>): MiniThreeScope;
|
|
137
|
+
function getActiveScope(): MiniThreeScope; // 未初始化时返回占位对象,见下
|
|
138
|
+
function setActiveScope(scope: MiniThreeScope | null): () => void;
|
|
139
|
+
function hasActiveScope(): boolean;
|
|
140
|
+
function installGlobals(scope, options?): () => void;
|
|
141
|
+
function getEarlyScopeReads(): readonly string[]; // 未初始化时被读过的全局名
|
|
142
|
+
function clearEarlyScopeReads(): void;
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
未初始化时的占位对象有两条不同策略:
|
|
146
|
+
|
|
147
|
+
- `window` / `self` / `globalThis` 指向自身,`typeof window === 'object'`,与 three 的特性检测假设一致;
|
|
148
|
+
- `document` / `navigator` / `screen` / `location` / `history` 读作 `undefined`,等价于「这个宿主没有 DOM」。`typeof` 对这些键永不抛错,包括构建插件无法守卫的 `typeof window.document` 形态;
|
|
149
|
+
- 其余键(`HTMLCanvasElement`、`TextDecoder`、`Blob` …)读取即抛错,因为那不是探测而是真实使用,静默 `undefined` 只会在几帧之后以无关的形式爆掉。
|
|
150
|
+
|
|
151
|
+
这些「读作 `undefined`」的早读会被记录,`createRuntime()` 启动后 `warnOnce` 汇总一次(提示 `three` 求值过早),随后清空。
|
|
152
|
+
|
|
153
|
+
`MiniThreeScope` 同时扮演 `window` / `self` / `globalThis`(三者指向自身),并包含:
|
|
154
|
+
|
|
155
|
+
- 领域对象:`document`、`navigator`、`screen`、`performance`、`getComputedStyle`、`matchMedia`;
|
|
156
|
+
- 尺寸:`innerWidth`、`innerHeight`、`outerWidth`、`outerHeight`、`devicePixelRatio`、`pageXOffset`、`pageYOffset`(均为 live getter);
|
|
157
|
+
- 事件:`Event`、`EventTarget`、`CustomEvent`、`PointerEvent`、`MouseEvent`、`TouchEvent`、`MessageEvent`、`ProgressEvent`、`KeyboardEvent`、`DOMException`;
|
|
158
|
+
- DOM:`HTMLElement`、`HTMLCanvasElement`、`HTMLImageElement`、`OffscreenCanvas`、`Image`、`ImageData`、`DOMRect`、`WebGLRenderingContext`、`WebGL2RenderingContext`、`AudioContext`;
|
|
159
|
+
- 网络/编码:`Blob`、`URL`、`TextEncoder`、`TextDecoder`、`fetch`、`XMLHttpRequest`、`AbortController`、`AbortSignal`、`atob`、`btoa`;
|
|
160
|
+
- 帧:`requestAnimationFrame`、`cancelAnimationFrame`;
|
|
161
|
+
- 明确不可用:`createImageBitmap`、`FileReader`、`WebSocket` 为 `undefined`(让 three 走降级分支)。
|
|
162
|
+
|
|
163
|
+
`installGlobals(scope, { target?, skipExisting?, extraKeys? })` 把上述键定义为 `globalThis` 上的 getter;返回的 disposer 会精确还原原有 descriptor。
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## 4.4 core 子路径
|
|
168
|
+
|
|
169
|
+
| API | 签名 / 说明 |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `patchElement(instance, options)` | 就地补 DOM 属性,返回 `{ element, updateRect, disposers }`。`options.nativeEventTarget: true` 表示目标自带原生事件系统:跳过 `patchEventTarget`,且只补**缺失**的成员(`style` / `getBoundingClientRect` / `setPointerCapture` 等留给宿主),见 [ADR-0010](./adr/0010-native-event-target-boundary.md) |
|
|
172
|
+
| `createMockClass(name)` | 生成带 `Symbol.hasInstance` + `WeakSet` 的构造器 shim |
|
|
173
|
+
| `markAs(ctor, obj)` / `isMarked(ctor, obj)` | 注册 / 查询 instanceof 关系 |
|
|
174
|
+
| `*Shim` | `HTMLCanvasElementShim`、`HTMLImageElementShim`、`HTMLElementShim`、`OffscreenCanvasShim`、`ImageDataShim`、`WebGLRenderingContextShim`、`WebGL2RenderingContextShim`、`DOMRectShim` |
|
|
175
|
+
| `patchCanvas(raw, options)` | 返回 `{ canvas, contexts, updateRect, element, disposers }`。`nativeEventTarget` 透传给 `patchElement`;无论哪种模式都接管 `getContext`(上下文缓存 + WebGL 归一化) |
|
|
176
|
+
| `createOffscreenCanvas(wx, w?, h?, options?)` | 直接创建并补丁离屏画布 |
|
|
177
|
+
| `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }`。工厂按「原生 `addEventListener` → `onload`/`onerror` 赋值 → `wx.getImageInfo` → 2s watchdog」四级兜底把宿主事件桥接成合成事件:`img.onload = fn` 与 `addEventListener('load', fn)` 都能收到通知,`complete` 在成功/失败后都为 `true`,`decode()` 据此 resolve/reject。宿主两种消费时序都覆盖:**赋值即存**(模拟器)与**事件触发时读属性**(真机)——`onload`/`onerror` 访问器在非派发期间永远返回可调用的桥接函数,只有 `dispatchEvent` 行内派发期间返回登记的用户回调,见 [ADR-0011](./adr/0011-host-callback-slot-bridging.md)。watchdog 对所有宿主无条件生效:`src` 赋值后 2s 内没有真实事件时,`complete` 为真则派发 `load`,否则派发带 `reason` 的 `error` 并 `warnOnce('image-events-timeout', …, { path, src })`,不会无限 pending 也不会无告警 |
|
|
178
|
+
| `createDocument(options)` / `createScreen(w, h)` / `ShimDOMRect` | 伪 DOM 容器 |
|
|
179
|
+
| `PointerBridge` | `dispatch(event, opts?)`、`dispatchMouse(event)`、`setRect`、`refreshRect`、`setPointerCapture`、`releasePointerCapture`、`activePointerCount`、`dispose`。构造选项 `createEvent(type, init)` 存在时派发**真实 DOM 事件**而不是 `MiniEvent`;`nativeEventTarget: true` 时不再向 `document` / `window` 转派(浏览器自己冒泡),见 [ADR-0010](./adr/0010-native-event-target-boundary.md) |
|
|
180
|
+
| `createFrameScheduler(raf, caf, options)` | `request` / `cancel` / `loop(cb)` / `setFpsCap` / `fps` / `dispose` |
|
|
181
|
+
| `createWindowInfoStore(wx, options)` | `info` / `refresh()` / `onChange()` / `setPixelRatioCap()` / `dispose()` |
|
|
182
|
+
| `detectCapabilities(wx, platform, options)` / `versionAtLeast(a, b)` | 能力探测。`options.probeContext(type)` 返回 `true` / `false` / `undefined`,**`undefined` 表示「探测不到」而不是「不支持」**,此时 `webgl2` 按基础库版本推断并在 `webgl2Source` 里标记为 `'inferred'` |
|
|
183
|
+
| `createDiagnostics(level, reporter)` / `capabilityReport(caps)` | 日志与报告 |
|
|
184
|
+
| `currentScope()` | 返回当前作用域或 `null` |
|
|
185
|
+
|
|
186
|
+
### `PlatformBinding`(新增平台时实现)
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
interface PlatformBinding {
|
|
190
|
+
readonly kind: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
|
|
191
|
+
readonly wx?: WxLike;
|
|
192
|
+
readonly rawCanvas: WxCanvas;
|
|
193
|
+
readonly capabilities: Capabilities;
|
|
194
|
+
readonly imageFactory: ImageFactory;
|
|
195
|
+
/** true = rawCanvas 自带原生事件系统(浏览器)。缺省 false(微信裸对象)。 */
|
|
196
|
+
readonly nativeEventTarget?: boolean;
|
|
197
|
+
/** nativeEventTarget 为真时构造真实 DOM 事件。 */
|
|
198
|
+
createEvent?(type: string, init: NativeEventInit): unknown;
|
|
199
|
+
getCanvasRect(): Rect | Promise<Rect>;
|
|
200
|
+
createOffscreenCanvas(w: number, h: number, type: ContextType): WxCanvas;
|
|
201
|
+
watchTouch(handler: (e: TouchLikeEvent) => void): Disposer;
|
|
202
|
+
watchVisibility(handler: (visible: boolean) => void): Disposer;
|
|
203
|
+
requestAnimationFrame(cb: (time: number) => void): number;
|
|
204
|
+
cancelAnimationFrame(id: number): void;
|
|
205
|
+
now(): number;
|
|
206
|
+
dispose(): void;
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
`nativeEventTarget` 决定的是**归属**而不是能力:为真时 `addEventListener` / `dispatchEvent` / `style` / `getBoundingClientRect` 全部留给宿主,适配层只在缺失时补;为假时按 [ADR-0004](./adr/0004-in-place-patching.md) 用 `MiniEventTarget` 接管。自己实现新平台时,如果宿主是裸对象(小程序、小游戏、原生渲染层)就保持缺省;只有目标本身就是标准 DOM 元素时才置真。
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 4.5 polyfills 子路径
|
|
215
|
+
|
|
216
|
+
| API | 说明 |
|
|
217
|
+
| --- | --- |
|
|
218
|
+
| `MiniEvent` / `MiniCustomEvent` / `MiniPointerEvent` / `MiniMouseEvent` / `MiniMessageEvent` / `MiniProgressEvent` / `MiniDOMException` | 事件对象 |
|
|
219
|
+
| `MiniEventTarget` / `patchEventTarget(obj)` | 事件目标;`patchEventTarget` 不改变对象身份。监听器被调用时 `this`、`event.target`、`event.currentTarget` 都是**宿主元素**而不是内部载体——three 的 `ImageLoader` 用 `this` 取 `<img>` 当纹理源,拿错对象就等于没有像素。`dispatchEvent()` 只对 `MiniEvent` 实例写 `target` / `currentTarget`:真实 DOM `Event` 的这两个字段是只读访问器,写入会在严格模式下抛错(见 ADR-0010) |
|
|
220
|
+
| `MiniBlob` | `bytes()`、`arrayBuffer()`、`text()`、`slice()`、`dataURL()`、`size`、`type` |
|
|
221
|
+
| `MiniURL` | `createObjectURL` / `revokeObjectURL` / `resolveObjectURL` / `clearObjectURLs`;构造器支持相对路径解析 |
|
|
222
|
+
| `MiniURLSearchParams` | `get` / `set` / `toString` |
|
|
223
|
+
| `bytesToBase64` / `base64ToBytes` / `resolveUrl` | 编码与 URL 工具 |
|
|
224
|
+
| `atob` / `btoa` / `MiniTextEncoder` / `MiniTextDecoder` | 编码 |
|
|
225
|
+
| `createFetch(wx)` / `MiniXMLHttpRequest` / `createXMLHttpRequestFactory(wx)` / `MiniAbortController` / `MiniAbortSignal` | 网络 |
|
|
226
|
+
|
|
227
|
+
> 注意:对象 URL 采用 `mini-three-blob:` 前缀并解析为 `data:` URI,而不是浏览器 `blob:` ——因为微信 image loader 只认 `data:` / 本地路径。
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 4.6 构建插件
|
|
232
|
+
|
|
233
|
+
### Vite
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
import miniThree from 'mini-three-adapter/vite';
|
|
237
|
+
plugins: [miniThree(options)];
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
插件额外提供 `config()`,设置 `optimizeDeps.exclude: ['three', 'three-stdlib', 'three/examples/jsm']`,确保 AST 重写见到原始 ESM 模块图。
|
|
241
|
+
|
|
242
|
+
### Rollup
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { miniThree } from 'mini-three-adapter/rollup';
|
|
246
|
+
plugins: [miniThree(options)];
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### `MiniThreePluginOptions`
|
|
250
|
+
|
|
251
|
+
| 选项 | 类型 | 默认 | 说明 |
|
|
252
|
+
| --- | --- | --- | --- |
|
|
253
|
+
| `include` | `(id: string) => boolean` | 匹配 `three` / `three-stdlib` / `@react-three` / `@tresjs` / `.vite/deps/three*` | 需要重写的模块 |
|
|
254
|
+
| `exclude` | `(id: string) => boolean` | `() => false` | 排除 |
|
|
255
|
+
| `includeUserCode` | `boolean` | `false` | 是否也改写应用代码 |
|
|
256
|
+
| `rewrite` | `RewriteOptions` | — | 高级重写配置 |
|
|
257
|
+
| `webgpu` | `'warn' \| 'error' \| 'rewrite' \| 'ignore'` | `'warn'` | 遇到 `three/webgpu` 的策略 |
|
|
258
|
+
| `roots` | `string[]` | three jsm/libs、`three-stdlib`、`public`、`static` | 资源搜索目录 |
|
|
259
|
+
| `outputDir` | `string` | `'assets/three'` | 资源输出目录 |
|
|
260
|
+
| `brotli` | `boolean` | `true` | 同时拷贝 `.wasm.br` |
|
|
261
|
+
| `manifest` | `boolean` | `true` | 输出 `mini-three-assets.json` |
|
|
262
|
+
| `cwd` | `string` | `process.cwd()` | 解析 roots 的根目录 |
|
|
263
|
+
| `report` | `boolean` | `true` | 打印构建摘要 |
|
|
264
|
+
| `debug` | `boolean` | `false` | 逐模块日志 |
|
|
265
|
+
|
|
266
|
+
### `RewriteOptions`
|
|
267
|
+
|
|
268
|
+
| 选项 | 默认 | 说明 |
|
|
269
|
+
| --- | --- | --- |
|
|
270
|
+
| `globals` | `DEFAULT_GLOBAL_NAMES` | 替换默认清单(而非追加) |
|
|
271
|
+
| `extraGlobals` | `[]` | 追加清单 |
|
|
272
|
+
| `forceUndef` | `['createImageBitmap']` | 强制走 `__m3().x`(作用域中恒为 `undefined`) |
|
|
273
|
+
| `accessor` | `'__m3'` | 注入的 `getActiveScope` 别名 |
|
|
274
|
+
| `scopeModule` | `'mini-three-adapter/scope'` | 注入的 import 路径 |
|
|
275
|
+
|
|
276
|
+
### 高级导出(`mini-three-adapter/rollup`)
|
|
277
|
+
|
|
278
|
+
`rewriteGlobals(code, id, options)`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF`、`collectAssetReferences`、`collectAssets`、`copyAssets`、`miniThreePlugin`。
|
|
279
|
+
|
|
280
|
+
`plugin.api.report()` → `BuildReport`:`modulesScanned`、`modulesRewritten`、`rewrites`、`globalsSeen`、`assetReferences`、`missingAssets`、`webgpuWarnings`、`parseFailures`。
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## 4.7 类型速查
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
interface Capabilities {
|
|
288
|
+
platform: 'wechat-game' | 'wechat-miniprogram' | 'browser' | 'unknown';
|
|
289
|
+
webgl2: boolean;
|
|
290
|
+
/** 'probe' 实测 / 'inferred' 版本推断 / 'override' 调用方覆盖 */
|
|
291
|
+
webgl2Source?: 'probe' | 'inferred' | 'override';
|
|
292
|
+
webgl1: boolean; offscreenCanvas: boolean;
|
|
293
|
+
worker: boolean; wasm: boolean; brotliWasm: boolean; nativeImage: boolean;
|
|
294
|
+
triggerGC: boolean; getWindowInfo: boolean; windowResizeEvent: boolean;
|
|
295
|
+
baseLibraryVersion: string;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
interface WindowInfo {
|
|
299
|
+
width: number; height: number; pixelRatio: number; rawPixelRatio: number;
|
|
300
|
+
safeArea?: Rect;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
interface Rect { top: number; left: number; width: number; height: number; right: number; bottom: number; }
|
|
304
|
+
|
|
305
|
+
interface TouchLikeEvent {
|
|
306
|
+
type: string; touches?: ArrayLike<TouchPoint>;
|
|
307
|
+
changedTouches?: ArrayLike<TouchPoint>; timeStamp?: number;
|
|
308
|
+
[key: string]: unknown;
|
|
309
|
+
}
|
|
310
|
+
```
|