from __future__ import annotations

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


def 输入文本(
    元素对象: Any,
    文本: str,
    回车确认: bool = False
) -> bool:
    """
    向指定网页元素输入文本内容，并可选择在输入完成后自动发送回车键。

    本函数用于向输入框、搜索框、登录框等可编辑元素写入文本内容，
    底层通过 Selenium 的 `send_keys` 方法实现。

    在部分网站中，输入完成后无需额外点击按钮，只需发送回车键即可
    触发表单提交、搜索请求或登录操作，因此提供 `回车确认` 参数以
    支持此类场景。

    Args:
        元素对象 (Any):
            Selenium WebElement 元素对象，通常由元素定位函数返回，
            例如输入框、搜索框或其他支持文本输入的元素。

        文本 (str):
            需要输入到元素中的文本内容。

        回车确认 (bool, optional):
            是否在文本输入完成后自动发送回车键。
            - True  ：输入文本后发送 ENTER
            - False ：仅输入文本
            默认值为 False。

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

    Notes:
        - 本函数内部不会主动抛出异常，以保持工具库统一的调用风格。
        - 若元素对象失效（例如页面刷新后元素引用失效），
          `send_keys` 可能触发异常，此时函数返回 False。
        - 对于需要逐字符输入或模拟人工输入速度的场景，
          建议在更高层函数中进行封装控制。
    """
    try:
        if 元素对象 is None:
            return False

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

        元素对象.send_keys(文本)

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

        return True

    except Exception:
        return False