from __future__ import annotations

import time
from typing import Any
from selenium.webdriver.common.keys import Keys


def 输入文本_逐字(
    元素对象: Any,
    文本: str,
    输入间隔: float = 0.05,
    回车确认: bool = False
) -> bool:
    """
    向指定网页元素逐字符输入文本（模拟真人输入）。

    本函数会将文本拆分为单个字符，并逐个发送到目标元素，
    每个字符之间保持一定时间间隔，以模拟真实用户键盘输入行为。

    该方式适用于以下场景：
        - 需要触发 keydown / keyup 监听事件
        - 页面存在实时搜索 / 实时校验逻辑
        - 需要降低自动化行为特征（反机器人检测）
        - 调试自动化脚本时观察输入过程

    Args:
        元素对象 (Any):
            Selenium WebElement 元素对象，例如输入框、搜索框等。

        文本 (str):
            需要输入的文本内容。

        输入间隔 (float, optional):
            每个字符之间的输入延迟（秒）。
            默认值为 0.05 秒。

        回车确认 (bool, optional):
            输入完成后是否自动发送回车键。
            默认 False。

    Returns:
        bool:
            True  ：输入成功
            False ：输入失败或发生异常

    Notes:
        - 本函数不会主动抛出异常，以保持工具库统一风格。
        - 输入间隔越小，输入速度越快；越大则越接近真人输入。
        - 若需要更高仿真人输入，可在更高层逻辑中加入随机延迟。
    """
    try:
        if 元素对象 is None:
            return False

        if not isinstance(文本, str):
            文本 = str(文本)

        for 字符 in 文本:
            元素对象.send_keys(字符)
            time.sleep(输入间隔)

        if 回车确认:
            元素对象.send_keys(Keys.ENTER)

        return True

    except Exception:
        return False