init: 2.B

This commit is contained in:
AncTe committed 2026-02-28 20:23:34 +08:00
commit 6bf32174d8
610 files changed
+151444

No files matched your search

+97
View File
@@ -0,0 +1,97 @@
# GameUI API 文档
本文档由 `DeepSeek R1` 模型生成并微调。
```mermaid
graph LR
GameUI --> IGameUI
```
_实现 `IGameUI` 接口_
## 接口描述
`IGameUI<C>` 是 UI 系统的核心接口,定义了 UI 实例的基础结构和静态操作方法。
---
## 属性说明
| 属性名 | 类型 | 描述 |
| -------------- | ---------------------------------- | ------------------------------------------------------------------- |
| `name` | `string` | 只读,UI 的唯一标识名称 |
| `component` | `C extends UIComponent` | 只读,关联的 Vue 组件实例 |
| `list`(静态) | `Map<string, GameUI<UIComponent>>` | 静态属性,存储所有已注册的 UI 实例,键为 `name`,值为 `GameUI` 实例 |
---
## 构造方法
### `consturctor`
```typescript
function constructor(name: string, component: C): GameUI;
```
- **参数**
- `name`: UI 的唯一标识名称
- `component`: 关联的 Vue 组件实例
**示例**
```typescript
import { defineComponent } from 'vue';
export const MyComponent = defineComponent(...);
// 创建 UI 实例并自动注册到静态列表
export const MyUI = new GameUI('my-ui', MyComponent);
```
---
## 方法说明
### `GameUI.get`
```typescript
function get<T extends UIComponent>(id: string): GameUI<T> | null;
```
**静态方法**:根据 UI 名称从静态列表获取实例。
- **参数**
- `id`: UI 的唯一标识名称
- **返回值**
匹配的 `GameUI` 实例,未找到时返回 `null`
**示例**
```typescript
// 获取名为 "home" 的 UI 实例
const ui = GameUI.get<MyComponent>('my-ui');
if (ui) {
console.log(ui.component); // 输出关联的 Vue 组件
}
```
---
## 总使用示例
```tsx
import { defineComponent } from 'vue';
import { GameUI } from '@motajs/system-ui';
// 定义组件
export const MyCom = defineComponent(() => {
return () => (
<container>
<text text="自定义组件 UI" />
</container>
);
});
// 定义 UI 实例
export const MyUI = new GameUI('my-ui', MyCom);
```
+284
View File
@@ -0,0 +1,284 @@
# UIController API 文档
本文档由 `DeepSeek R1` 模型生成并微调。
```mermaid
graph LR
UIController --> EventEmitter
click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
```
## 类描述
`UIController` 是 UI 控制系统的核心类,负责管理 UI 实例的显示栈、背景控制以及多种显示模式。继承自 `EventEmitter`,支持事件监听。想要编写 UI 请参考[深度指南](../../guide/ui/ui.md)。
---
## 属性说明
| 属性名 | 类型 | 描述 |
| --------------------- | ---------------------------- | --------------------------------------------------------------- |
| `stack` | `IUIInstance[]` (响应式数组) | 当前管理的 UI 实例栈 |
| `mode` | `UIMode` | UI 显示模式,默认为 `LastOnlyStack` |
| `background` | `IGameUI` | 背景 UI 的配置实例 |
| `backIns` | `ShallowRef<IUIInstance>` | 背景 UI 实例的响应式引用 |
| `showBack` | `ComputedRef<boolean>` | 当前是否显示背景(用户设置与系统状态共同决定) |
| `active`(只读) | `boolean` | 系统是否显示背景 UI(等价于 `sysShowBack.value`) |
| `controllers`(静态) | `Map<string, UIController>` | 静态属性,存储所有已创建的控制器实例,键为 `id`,值为控制器实例 |
---
## 构造方法
### `constructor`
```typescript
function constructor(id: string): UIController;
```
- **参数**
- `id`: 控制器的唯一标识符(若重复会触发警告日志)
**示例**
```typescript
const mainController = new UIController('main');
```
---
## 方法说明
### `render`
```typescript
function render(): VNode;
```
渲染 UI 容器组件(用于 Vue 挂载)。
**示例**
```tsx
import { defineComponent } from 'vue';
import { UIController } from '@motajs/system-ui';
export const myController = new UIController('my-controller');
export const MyCom = defineComponent(() => {
return () => <container>{myController.render()}</container>;
});
```
---
### `setBackground`
```typescript
function setBackground<T extends UIComponent>(
back: IGameUI<T>,
vBind: UIProps<T>
): void;
```
设置背景 UI 并初始化其实例。
- **参数**
- `back`: 背景 UI 配置实例
- `vBind`: 传递给背景组件的 Props 对象
**示例**
```typescript
import { BackgroundUI } from './background';
// 显示背景组件,并传入参数 theme='dark'
mainController.setBackground(BackgroundUI, { theme: 'dark' });
```
---
### `hideBackground`
```typescript
function hideBackground(): void;
```
隐藏背景 UI (不影响系统状态)。
---
### `showBackground`
```typescript
function showBackground(): void;
```
显示背景 UI(不影响系统状态)。
---
### `keep`
```typescript
function keep(): IKeepController;
```
维持背景显示(防闪烁),返回控制器对象:
```typescript
interface IKeepController {
safelyUnload(): void; // 安全卸载(仅在栈为空时关闭)
unload(): void; // 强制立即卸载
}
```
**示例**
```typescript
const keeper = mainController.keep();
// 执行某些操作后...
keeper.safelyUnload();
```
---
### `open`
```typescript
function open<T extends UIComponent>(
ui: IGameUI<T>,
vBind: UIProps<T>,
alwaysShow?: boolean
): IUIInstance<T>;
```
打开一个新 UI 实例并加入栈中。
- **参数**
- `ui`: UI 配置实例
- `vBind`: 组件 Props
- `alwaysShow`: 是否强制显示(默认 `false`)
- **返回值**
打开的 UI 实例,可以用于关闭等操作
**示例**
```typescript
import { MyUI } from './myUI';
const instance = mainController.open(MyUI, { param: 80 });
```
---
### `close`
```typescript
function close(ui: IUIInstance): void;
```
关闭指定 UI 实例(根据当前模式可能影响其他实例)。
---
### `closeAll`
```typescript
function closeAll(ui?: IGameUI): void;
```
关闭所有或指定类型的所有 UI 实例。
- **参数**
- `ui`(可选): 指定要关闭的 UI 类型,不填时表示关闭所有 UI
---
### `lastOnly`
```typescript
function lastOnly(stack?: boolean): void;
```
切换显示模式:仅显示最后一个 UI(可设置为栈模式)
---
### `showAll`
```typescript
function showAll(stack?: boolean): void;
```
切换显示模式:显示所有非隐藏 UI(可设置为栈模式)
---
### `showCustom`
```typescript
function showCustom(config: IUICustomConfig): void;
```
切换显示模式:使用自定义模式(需实现 `IUICustomConfig`),参考[指南](../../guide/ui/system.md#自定义显示模式)
---
### `UIController.getController`
```typescript
function getController(id: string): UIController | null;
```
**静态方法**:根据 ID 获取控制器实例。
**示例**
```typescript
const ctrl = UIController.getController('main');
```
---
## 事件说明
| 事件名 | 参数类型 | 触发时机 |
| ------- | ------------------------------- | ------------------ |
| `open` | `ui: IGameUI, ins: IUIInstance` | 新 UI 实例被打开时 |
| `close` | `ins: IUIInstance` | UI 实例被关闭时 |
**事件监听示例**
```typescript
mainController.on('open', (ui, ins) => {
console.log(`Opened UI: ${ui.name}`);
});
```
---
## 总使用示例
```typescript
import { BackgroundUI, DialogUI } from './myUI';
import { mainController } from '@user/client-modules';
// 事件监听
mainController.on('close', ins => {
console.log('UI closed:', ins.ui.name);
});
// 设置背景
mainController.setBackground(BackgroundUI, { color: '#333' });
// 打开 UI
const dialogIns = mainController.open(DialogUI, { title: '提示' });
// 切换显示模式,仅显示最后一个,启用栈模式
mainController.lastOnly(true);
// 关闭 UI
mainController.close(dialogIns);
```
+121
View File
@@ -0,0 +1,121 @@
# UIInstance API 文档
本文档由 `DeepSeek R1` 模型生成并微调。
```mermaid
graph LR
UIInstance --> IUIInstance
```
_实现 `IUIInstance` 接口_
## 类描述
`UIInstance` 表示通过 `GameUI` 模板创建的具体 UI 实例,用于管理单个 UI 实例的状态和数据绑定。实现了 `IUIInstance` 接口。
---
## 属性说明
| 属性名 | 类型 | 描述 |
| ------------ | ------------ | -------------------------------------------------------- |
| `key` | `number` | 只读,实例的唯一标识(用于 Vue 的 `key` 属性) |
| `ui` | `IGameUI<C>` | 只读,关联的 UI 配置实例(即创建该实例的 `GameUI` 模板) |
| `vBind` | `UIProps<C>` | 只读,传递给 UI 组件的响应式 Props 对象 |
| `hidden` | `boolean` | 当前实例是否处于隐藏状态 |
| `alwaysShow` | `boolean` | 是否强制保持显示(不受显示模式影响) |
---
## 构造方法
```typescript
function constructor(
ui: IGameUI<C>,
vBind: UIProps<C>,
alwaysShow: boolean = false
): UIInstance;
```
- **参数**
- `ui`: 关联的 `GameUI` 配置实例
- `vBind`: 初始化的组件 Props 对象
- `alwaysShow`: 是否强制保持显示(默认 `false`)
**注意事项**:一般不需要手动创建 `UIInstance` 实例,请使用 [`UIController.open`](./UIController.md#open) 打开 UI 并创建实例。
---
## 方法说明
### `setVBind`
```typescript
function setVBind(data: Partial<Props<C>>, merge?: boolean): void;
```
更新组件的响应式 Props。
- **参数**
- `data`: 需要更新的数据(部分 Props)
- `merge`: 是否与现有数据合并(默认 `true`),若为 `false` 则完全覆盖
**示例**
```typescript
// 合并更新音量值
instance.setVBind({ volume: 60 });
// 覆盖所有 Props
instance.setVBind({ theme: 'dark' }, false);
```
---
### `hide`
```typescript
function hide(): void;
```
控制实例的显示状态(直接操作 `hidden` 属性)。
**示例**
```typescript
instance.hide(); // 隐藏 UI
setTimeout(() => instance.show(), 1000); // 1 秒后显示
```
---
### `show`
```typescript
function show(): void;
```
控制实例的显示状态(直接操作 `hidden` 属性)。
**示例**
```typescript
instance.show(); // 隐藏 UI
setTimeout(() => instance.show(), 1000); // 1 秒后显示
```
---
## 总使用示例
```typescript
import { myController, MyUI } from './myUI';
const myIns = myController.open(MyUI, { title: '警告' });
// 动态更新 props
myIns.setVBind({ title: '错误' });
// 设置显示状态
myIns.show();
```
+3
View File
@@ -0,0 +1,3 @@
# @motajs/system-ui
目录: