mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-20 13:02:58 +08:00
316 lines
9.9 KiB
Markdown
316 lines
9.9 KiB
Markdown
# InputBox 输入对话框组件 API 文档
|
||
|
||
本文档由 `DeepSeek` 生成并微调。
|
||
|
||
## 组件描述
|
||
|
||
输入对话框组件是一个完整的弹出式输入界面，包含提示文本、输入框、确认和取消按钮。适用于需要用户输入文本的交互场景，提供了便捷的异步获取输入方法。
|
||
|
||
---
|
||
|
||
## Props 属性说明
|
||
|
||
| 属性名 | 类型 | 默认值 | 描述 |
|
||
| ------------------------- | ---------------- | -------- | ----------------------------------------------------- |
|
||
| `loc` | `ElementLocator` | 必填 | 输入框对话框的位置 |
|
||
| `input` | `InputProps` | - | 传递给内部 Input 组件的配置参数 |
|
||
| `winskin` | `ImageIds` | - | 窗口皮肤图片ID，用于对话框背景绘制 |
|
||
| `color` | `CanvasStyle` | - | 对话框背景颜色（未设置 winskin 时生效） |
|
||
| `border` | `CanvasStyle` | - | 对话框边框颜色（未设置 winskin 时生效） |
|
||
| `pad` | `number` | - | 对话框内部所有元素的内边距 |
|
||
| `inputHeight` | `number` | - | 内部输入框区域的高度 |
|
||
| `text` | `string` | - | 对话框顶部的提示文本 |
|
||
| `yesText` | `string` | `"确认"` | 确认按钮的显示文本 |
|
||
| `noText` | `string` | `"取消"` | 取消按钮的显示文本 |
|
||
| `selFont` | `Font` | - | 确认/取消按钮的字体样式 |
|
||
| `selFill` | `CanvasStyle` | - | 确认/取消按钮的文本颜色 |
|
||
| 继承自 `TextContentProps` | - | - | [查看完整属性](./组件%20TextContent#Props%20属性说明) |
|
||
|
||
---
|
||
|
||
## Events 事件说明
|
||
|
||
| 事件名 | 参数类型 | 触发时机 |
|
||
| -------------- | ----------------- | ------------------------------------------ |
|
||
| `confirm` | `(value: string)` | 当确认输入框的内容时触发 |
|
||
| `cancel` | `(value: string)` | 当取消时触发 |
|
||
| `change` | `(value: string)` | 继承自 Input 组件 - 输入框值被确认时触发 |
|
||
| `input` | `(value: string)` | 继承自 Input 组件 - 输入框值实时变化时触发 |
|
||
| `update:value` | `(value: string)` | 继承自 Input 组件 - v-model 双向绑定 |
|
||
|
||
---
|
||
|
||
## Slots 插槽说明
|
||
|
||
无插槽
|
||
|
||
---
|
||
|
||
## Exposed Methods 暴露方法
|
||
|
||
无暴露方法
|
||
|
||
---
|
||
|
||
## 工具函数
|
||
|
||
### `getInput(controller, text, loc, width, props?)`
|
||
|
||
弹出一个输入框并异步返回用户输入的结果。
|
||
|
||
**参数**
|
||
|
||
- `controller: IUIMountable` - UI 控制器
|
||
- `text: string` - 提示文本内容
|
||
- `loc: ElementLocator` - 确认框的位置
|
||
- `width: number` - 确认框的宽度
|
||
- `props?: InputBoxProps` - 额外的配置属性（可选）
|
||
|
||
**返回值**: `Promise<string>`
|
||
|
||
### `getInputNumber(controller, text, loc, width, props?)`
|
||
|
||
与 `getInput` 类似，但会将结果转换为数字。
|
||
|
||
**参数**: 同 `getInput`
|
||
**返回值**: `Promise<number>`
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基础用法 - 组件形式
|
||
|
||
```tsx
|
||
import { defineComponent, ref } from 'vue';
|
||
import { InputBox } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
const handleConfirm = (value: string) => {
|
||
console.log('用户输入:', value);
|
||
// 处理用户输入
|
||
};
|
||
|
||
const handleCancel = (value: string) => {
|
||
console.log('用户取消输入，最后值为:', value);
|
||
};
|
||
|
||
return () => (
|
||
<InputBox
|
||
text="请输入您的姓名："
|
||
loc={[240, 240, 300, 180, 0.5, 0.5]}
|
||
input={{
|
||
placeholder: '在此输入姓名',
|
||
border: '#007acc',
|
||
borderWidth: 1,
|
||
circle: [4],
|
||
pad: 8
|
||
}}
|
||
color="#ffffff"
|
||
border="#cccccc"
|
||
borderWidth={2}
|
||
pad={16}
|
||
inputHeight={40}
|
||
yesText="确定"
|
||
noText="取消"
|
||
onConfirm={handleConfirm}
|
||
onCancel={handleCancel}
|
||
/>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 使用 getInput 工具函数（推荐）
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
import { getInput, getInputNumber } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(props => {
|
||
const handleGetName = async () => {
|
||
// 获取文本输入
|
||
const name = await getInput(
|
||
props.controller,
|
||
'请输入您的姓名：',
|
||
[208, 208, void 0, void 0, 0.5, 0.5],
|
||
280,
|
||
{
|
||
input: {
|
||
placeholder: '姓名'
|
||
},
|
||
color: '#f8f8f8'
|
||
}
|
||
);
|
||
|
||
if (name) {
|
||
console.log('用户姓名:', name);
|
||
// 处理姓名
|
||
} else {
|
||
console.log('用户取消了输入');
|
||
}
|
||
};
|
||
|
||
const handleGetAge = async () => {
|
||
// 获取数字输入
|
||
const age = await getInputNumber(
|
||
props.controller,
|
||
'请输入您的年龄：',
|
||
[208, 208, void 0, void 0, 0.5, 0.5],
|
||
280
|
||
);
|
||
|
||
if (!isNaN(age)) {
|
||
console.log('用户年龄:', age);
|
||
// 处理年龄
|
||
}
|
||
};
|
||
|
||
return () => (
|
||
<container>
|
||
<text
|
||
loc={[240, 180, void 0, void 0, 0.5, 0.5]}
|
||
onClick={handleGetName}
|
||
text="输入姓名"
|
||
/>
|
||
<text
|
||
loc={[240, 220, void 0, void 0, 0.5, 0.5]}
|
||
onClick={handleGetAge}
|
||
text="输入年龄"
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 带自定义样式的输入对话框
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
import { getInput } from '@user/client-modules';
|
||
|
||
export const StyledInputCom = defineComponent(props => {
|
||
const handleStyledInput = async () => {
|
||
const value = await getInput(
|
||
props.controller,
|
||
'请输入任务描述：',
|
||
[240, 240, void 0, void 0, 0.5, 0.5],
|
||
320,
|
||
{
|
||
text: '任务创建',
|
||
input: {
|
||
placeholder: '描述任务内容...',
|
||
multiline: true,
|
||
border: '#4CAF50',
|
||
borderWidth: 2,
|
||
circle: 8,
|
||
pad: 12
|
||
},
|
||
color: '#ffffff',
|
||
border: '#4CAF50',
|
||
borderWidth: 3,
|
||
pad: 20,
|
||
inputHeight: 80,
|
||
yesText: '创建',
|
||
noText: '取消',
|
||
selFill: '#4CAF50'
|
||
}
|
||
);
|
||
|
||
if (value) {
|
||
console.log('创建任务:', value);
|
||
}
|
||
};
|
||
|
||
return () => (
|
||
<text
|
||
loc={[240, 240, void 0, void 0, 0.5, 0.5]}
|
||
onClick={handleStyledInput}
|
||
text="创建新任务"
|
||
/>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 游戏中的设置界面
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
import { getInput } from '@user/client-modules';
|
||
|
||
export const SettingsCom = defineComponent(props => {
|
||
const settings = ref({
|
||
playerName: '玩家',
|
||
serverIP: '127.0.0.1'
|
||
});
|
||
|
||
const changePlayerName = async () => {
|
||
const newName = await getInput(
|
||
props.controller,
|
||
'修改玩家名称：',
|
||
[240, 240, void 0, void 0, 0.5, 0.5],
|
||
280,
|
||
{
|
||
input: {
|
||
value: settings.value.playerName,
|
||
placeholder: '玩家名称',
|
||
border: '#FF9800',
|
||
borderWidth: 1
|
||
}
|
||
}
|
||
);
|
||
|
||
if (newName) {
|
||
settings.value.playerName = newName;
|
||
console.log('玩家名称已更新:', newName);
|
||
}
|
||
};
|
||
|
||
const changeServerIP = async () => {
|
||
const newIP = await getInput(
|
||
props.controller,
|
||
'修改服务器IP：',
|
||
[240, 240, void 0, void 0, 0.5, 0.5],
|
||
280,
|
||
{
|
||
input: {
|
||
value: settings.value.serverIP,
|
||
placeholder: '服务器IP地址',
|
||
border: '#2196F3',
|
||
borderWidth: 1
|
||
}
|
||
}
|
||
);
|
||
|
||
if (newIP) {
|
||
settings.value.serverIP = newIP;
|
||
console.log('服务器IP已更新:', newIP);
|
||
}
|
||
};
|
||
|
||
return () => (
|
||
<container loc={[240, 240, 300, 200, 0.5, 0.5]}>
|
||
<text
|
||
loc={[0, -40, void 0, void 0, 0.5, 0.5]}
|
||
onClick={changePlayerName}
|
||
text={`玩家名称: ${settings.value.playerName}`}
|
||
/>
|
||
<text
|
||
loc={[0, 0, void 0, void 0, 0.5, 0.5]}
|
||
onClick={changeServerIP}
|
||
text={`服务器IP: ${settings.value.serverIP}`}
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **推荐使用工具函数**: `getInput` 和 `getInputNumber` 提供了更简洁的异步输入获取方式
|
||
2. **宽度设置**: 在使用工具函数时，高度由组件自动计算，只需指定宽度
|
||
3. **皮肤优先级**: 如果设置了 `winskin`，则 `color` 和 `border` 设置将失效
|
||
4. **异步处理**: 工具函数返回 Promise，需要使用 `await` 或 `.then()` 处理结果
|
||
5. **空值处理**: 用户取消输入时，`getInput` 返回空字符串，`getInputNumber` 返回 `NaN`
|