def 时间字符串转秒数(时间字符串: str) -> int | None:
    """把 ``HH:MM:SS`` 格式的时间字符串换算成总秒数。

    功能说明:
        - 这个函数用于把时分秒格式的字符串，换算成一个整数秒数。
        - 适合做倒计时、持续时长统计、播放时长换算等场景。
        - 输入内容必须能拆成小时、分钟、秒三个整数。
        - 输入格式不正确时，函数返回 ``None``。

    Args:
        时间字符串: 形如 ``HH:MM:SS`` 的时间字符串。

    Returns:
        成功时返回总秒数；失败时返回 ``None``。
    """
    try:
        时, 分, 秒 = map(int, 时间字符串.strip().split(":"))
        return 时 * 3600 + 分 * 60 + 秒
    except Exception:
        return None


if __name__ == "__main__":
    print("===== 示例1：标准时间字符串转秒数 =====")
    print("结果:", 时间字符串转秒数("01:02:03"))

    print("\n===== 示例2：全是 0 的时间字符串 =====")
    print("结果:", 时间字符串转秒数("00:00:00"))

    print("\n===== 示例3：大于 24 小时的时间字符串 =====")
    print("结果:", 时间字符串转秒数("36:15:20"))

    print("\n===== 示例4：缺少秒数部分 =====")
    print("结果:", 时间字符串转秒数("01:02"))

    print("\n===== 示例5：包含非数字字符 =====")
    print("结果:", 时间字符串转秒数("01:aa:03"))

    print("\n===== 示例6：应用场景-把视频时长换算成总秒数 =====")
    视频时长 = "00:48:30"
    print("视频总秒数:", 时间字符串转秒数(视频时长))
