SliderPy

SliderPy 是一个开箱即用、自动布局、支持持久化、跨平台兼容的 tkinter 滑动条管理器，让你用几行代码就能构建专业级的参数调节界面。 基于 tkinter，SliderPy 无需额外依赖即可直接运行。

🌟 核心功能亮点

1. 一键创建滑动条

• 通过 add_slider/add_sliders/add_slider_group/add_slider_groups 快速添加带标签的滑块
• 支持整数、浮点数（通过 resolution 控制精度）
• 滑块名称自动显示在标签上，实时更新当前值

2. 自动窗口布局管理

• ✅ 自动调整窗口高度：每添加一个滑块，窗口自动伸缩以完美包裹内容
• ✅ 固定宽度 + 禁止手动拉伸：保持界面整洁统一
• ✅ 启动时自动居中：在屏幕中央打开，提升用户体验

3. 灵活的事件回调

• 每个滑块可绑定独立回调函数，响应值变化
• 回调函数接收字符串值（符合 tkinter 规范），可自由处理

4. 重置与恢复

• 🔁 重置为默认初始值：reset_all_sliders()
• 🔙 重置为最近保存的配置：reset_to_config()

5. 配置持久化（JSON）

• 💾 保存当前参数到 JSON 文件
  • 默认保存到用户目录：~/.slider_app/config.json（跨平台）
  • 也支持手动选择保存路径
• 📂 从 JSON 加载配置
  • 自动裁剪非法值到合法范围
  • 提示缺失/多余参数
  • 可选：将加载的配置设为下次启动默认值

6. 启动自动恢复

• ✅ 程序启动时自动加载上次保存的配置
  • 无需用户操作，参数状态无缝延续
  • 配置文件不存在则静默跳过，无报错

7. 安全与健壮性

• 🛡️ 防止重复滑块名称：添加时检查唯一性
• 🛡️ 值范围保护：加载或设置时自动 clamp 到 [from_, to]
• 🛡️ 异常处理：文件读写错误弹窗提示，不崩溃
• 🛡️ 中文支持：JSON 使用 ensure_ascii=False，支持中文参数名

8. 开发者友好

• 📊 values属性：一键获取所有参数字典，便于调试或集成
• 🧱 面向对象封装：所有状态和方法集中管理，易于扩展
• 🧩 模块化设计：可轻松嵌入到更大项目中作为参数面板

9. 用户交互体验

• 🖱️ 图形化文件选择对话框（保存/加载）
• 💬 操作成功/失败均有弹窗反馈
• 🎨 界面简洁清晰，标签+滑块垂直排列，一目了然

📦 典型应用场景

• 🎨 图像/视频处理软件的参数调节（亮度、对比度、饱和度…）
• 🎵 音频合成器或均衡器控制
• 🧪 科研实验中的超参数调试
• 🤖 机器人或仿真环境的实时控制面板
• 🛠️ 任何需要快速构建“数值调节 UI”的 Python 工具

🚀 快速开始

if __name__ == "__main__":
    from pprint import pprint
    import time

    def on_brightness(val):
        assert isinstance(val, int)
        print(f"亮度变化: {val}")

    def on_volume(val):
        assert isinstance(val, float)
        print(f"音量: {float(val):.2f}")

    def on_target(val: dict):
        for v in val.values():
            assert isinstance(v, float)
        print(f"目标变化: {val}")

    def on_iter(val: tuple):
        assert isinstance(val, tuple)
        print(f"迭代器值: {val}")
        return f"iter_result={val}"

    app = SliderPy(base_width=500, config_path="./config.json")

    # add sliders
    sliders = (
        SliderConfig("亮度", 0, 100, 1.0, 70, on_brightness),
        SliderConfig("音量", 0, 1, 0.01, 0.6, on_volume),
        SliderConfig("对比度", 50, 150, 1.0, 100),
        SliderConfig("色温(K)", 2000, 10000, 100.0, 6500),
    )
    app.add_sliders(sliders)
    # add slider group
    app.add_slider_group(
        "target",
        (SliderConfig("X", 0, 1, 0.01), SliderConfig("Y", 0, 1, 0.01)),
        on_target,
    )
    # add iter slider
    app.add_iter_slider(
        {i: f"Item {i}" for i in range(20)}.items(),
        SliderConfig("iter", 0, 19, 1.0, 0, on_iter),
    )
    # finalize UI
    app.finish_add()
    # app.run()  # blockingly run the app
    pprint(app.values)

    def periodic_task():
        time.sleep(0.02)  # 模拟其他任务

    app.run(periodic_task)
    pprint(app.results)
    print("应用已关闭。")