HumanBreak/docs/api/user-client-modules/组件 InputBox.md

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	-	-	查看完整属性

---

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>

---

使用示例

基础用法 - 组件形式

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 工具函数（推荐）

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>
    );
});

带自定义样式的输入对话框

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="创建新任务"
        />
    );
});

游戏中的设置界面

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