init: 2.B

docs/api/user-client-modules/TextboxStore.md

@@ -0,0 +1,166 @@
+# TextboxStore API 文档
+
+本文档由 `DeepSeek R1` 模型生成并微调。
+
+---
+
+```mermaid
+graph LR
+    TextboxStore --> EventEmitter
+
+    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
+```
+
+---
+
+## 类描述
+
+`TextboxStore` 是文本框的集中管理器，继承自 `EventEmitter`。所有 `Textbox` 组件实例化时会自动注册到该类的静态 `list` 中，支持通过 ID 精准控制特定文本框。
+
+---
+
+## 核心方法说明
+
+### `TextboxStore.get`
+
+```typescript
+function get(id: string): TextboxStore | undefined;
+```
+
+**静态方法**：通过 ID 获取已注册的文本框控制器
+
+-   **参数**  
+    `id`: 文本框的唯一标识符
+-   **返回值**  
+    找到返回实例，否则返回 `undefined`
+
+---
+
+### `setText`
+
+```typescript
+function setText(text: string): void;
+```
+
+**动态更新文本内容**
+
+-   **特性**
+    -   自动重置打字机进度
+    -   触发重新排版计算
+
+---
+
+### `modify`
+
+```typescript
+function modify(data: Partial<TextboxProps>): void;
+```
+
+**动态修改文本框配置**
+
+-   **参数**  
+    `data`: 需更新的属性（支持所有 `TextboxProps` 属性）
+
+---
+
+### `endType`
+
+```typescript
+function endType(): void;
+```
+
+**立即结束打字机动画**
+
+-   **特性**
+    -   强制显示全部文本
+    -   触发 `typeEnd` 事件
+
+---
+
+### `show`
+
+```ts
+function show(): void;
+```
+
+### `hide`
+
+```ts
+function hide(): void;
+```
+
+控制文本框的显示和隐藏。
+
+---
+
+## 使用示例
+
+### 跨场景更新对话内容
+
+```typescript
+// 在剧情管理器中的调用
+const updateChapterDialog = (chapterId: string) => {
+    const store = TextboxStore.get(`chapter_${chapterId}`);
+    store?.setText(getChapterText(chapterId));
+    store?.modify({ title: `第 ${chapterId} 章` });
+};
+```
+
+### 紧急提示打断当前动画
+
+```typescript
+// 强制显示关键信息
+const showEmergencyAlert = () => {
+    const alertBox = TextboxStore.get('system_alert');
+    alertBox?.setText('警告！基地即将爆炸！');
+    alertBox?.endType(); // 跳过打字动画
+    alertBox?.show();
+};
+```
+
+### 动态样式调整
+
+```typescript
+// 根据昼夜切换对话框样式
+const updateDialogStyle = (isNight: boolean) => {
+    TextboxStore.list.forEach(store => {
+        store.modify({
+            backColor: isNight ? '#1A1A32' : '#F0F0FF',
+            titleFill: isNight ? '#E6E6FA' : '#2F4F4F'
+        });
+    });
+};
+```
+
+---
+
+## 注意事项
+
+1. **ID 管理规范**  
+   建议显式指定可预测的 ID 格式：
+
+    ```tsx
+    // 创建时指定可追踪 ID
+    <Textbox id={`npc_${npcId}_dialog`} ... />
+    ```
+
+2. **未找到实例处理**  
+   调用前需做空值检测：
+
+    ```typescript
+    const store = TextboxStore.get('custom_id');
+    if (!store) {
+        console.warn('文本框未注册: custom_id');
+        return;
+    }
+    ```
+
+3. **生命周期匹配**  
+   在组件卸载时自动注销实例，请勿持有长期引用
+
+4. **批量操作优化**  
+   同时操作多个实例时建议使用迭代器：
+    ```typescript
+    // 隐藏所有对话框
+    TextboxStore.list.forEach(store => store.hide());
+    ```