快格式技术文档

字段名	类型	必填	说明
`kuai`	String	✅	快格式版本号，当前版本为 "1.0"
`python_version`	Array	✅	支持的Python版本，如 ["3.8+"]
`os`	Array	✅	支持的操作系统，如 ["Windows"]
`packages`	Array	✅	依赖的第三方Python包列表
`name`	String	✅	脚本名称，显示在客户端界面
`description`	String	✅	脚本功能描述
`input_description`	String	✅	输入数据的描述
`output_description`	String	✅	输出数据的描述

快格式支持15种参数输入类型，每种类型都有特定的属性要求。参数必须定义在Params类的__init__方法中作为实例属性。

1. Radio (单选参数)

Radio 单选

用于从多个选项中选择一个值的单选按钮组。

"""
label: 图片格式选择
input_method: Radio
options:
    - JPEG
    - PNG
    - WebP
description: 选择输出图片的格式
"""
self.image_format: str = "JPEG"

必填属性：

label - 参数显示名称
input_method - 固定为 "Radio"
options - 选项列表（至少1个）
description - 参数说明

2. ToggleSwitch (开关参数)

ToggleSwitch 开关

用于启用或禁用某个功能的开关控件。

"""
label: 启用压缩功能
input_method: ToggleSwitch
description: 是否对输出文件进行压缩处理
"""
self.enable_compression: bool = False

必填属性：

label - 参数显示名称
input_method - 固定为 "ToggleSwitch"
description - 参数说明

3. Checkbox (多选参数)

Checkbox 多选

用于从多个选项中选择一个或多个值的复选框组。

"""
label: 处理选项
input_method: Checkbox
options:
    - 调整尺寸
    - 添加水印
    - 格式转换
min_select: 1
max_select: 3
description: 选择要执行的处理操作
"""
self.processing_options: [str] = []

必填属性：

label - 参数显示名称
input_method - 固定为 "Checkbox"
options - 选项列表（至少1个）
min_select - 最少选择数量
max_select - 最多选择数量
description - 参数说明

4. IntInput (整数输入)

IntInput 整数

用于输入整数值的数字输入框。

"""
label: 图片宽度
input_method: IntInput
unit: 像素
max: 4096
min: 1
description: 设置输出图片的宽度
"""
self.image_width: int = 800

必填属性：

label - 参数显示名称
input_method - 固定为 "IntInput"
unit - 数值单位
max - 最大值
min - 最小值
description - 参数说明

5. FloatInput (浮点数输入)

FloatInput 浮点数

用于输入浮点数值的数字输入框。

"""
label: 压缩质量
input_method: FloatInput
unit: %
max: 100.0
min: 0.1
precision: 2
description: 设置图片压缩质量百分比
"""
self.compression_quality: float = 85.0

必填属性：

label - 参数显示名称
input_method - 固定为 "FloatInput"
unit - 数值单位
max - 最大值
min - 最小值
precision - 小数位数
description - 参数说明

6. SingleLineTextInput (单行文本输入)

SingleLineTextInput 单行文本

用于输入单行文本的输入框，支持正则验证。

"""
label: 水印文字
input_method: SingleLineTextInput
max_length: 50
min_length: 1
required: true
validation: ^[\u4e00-\u9fa5a-zA-Z0-9\s]+$
validation_message: 只能包含中文、英文、数字和空格
description: 输入要添加的水印文字内容
"""
self.watermark_text: str = ""

必填属性：

label - 参数显示名称
input_method - 固定为 "SingleLineTextInput"
max_length - 最大字符数
min_length - 最小字符数
required - 是否可为空字符串
validation - 正则表达式验证
validation_message - 验证失败提示
description - 参数说明

7. MultiLineTextInput (多行文本输入)

MultiLineTextInput 多行文本

用于输入多行文本的文本域。

"""
label: 处理日志
input_method: MultiLineTextInput
max_length: 1000
min_length: 10
required: true
description: 输入处理过程的详细说明
"""
self.processing_log: str = ""

必填属性：

label - 参数显示名称
input_method - 固定为 "MultiLineTextInput"
max_length - 最大字符数
min_length - 最小字符数
required - 是否可为空字符串
description - 参数说明

8. SingleFilePicker (单文件选择)

SingleFilePicker 单文件

用于选择单个文件的文件选择器。

"""
label: 输入图片
input_method: SingleFilePicker
file_types:
    - jpg
    - jpeg
    - png
    - bmp
description: 选择要处理的图片文件
"""
self.input_image: str = ""

必填属性：

label - 参数显示名称
input_method - 固定为 "SingleFilePicker"
file_types - 允许的文件扩展名列表
description - 参数说明

9. MultiFilePicker (多文件选择)

MultiFilePicker 多文件

用于选择多个文件的文件选择器。

"""
label: 批量图片
input_method: MultiFilePicker
file_types:
    - jpg
    - png
min_files: 1
max_files: 100
description: 选择要批量处理的图片文件
"""
self.input_images: [str] = []

必填属性：

label - 参数显示名称
input_method - 固定为 "MultiFilePicker"
file_types - 允许的文件扩展名列表
min_files - 最少文件数量
max_files - 最多文件数量
description - 参数说明

10. SingleDirectoryPicker (目录选择)

SingleDirectoryPicker 目录选择

"""
label: 输出目录
input_method: SingleDirectoryPicker
description: 选择处理后文件的保存目录
"""
self.output_directory: str = ""

必填属性：

label - 参数显示名称
input_method - 固定为 "SingleDirectoryPicker"
description - 参数说明

Dropdown 下拉选择

用于从下拉列表中选择一个值的下拉选择器。

"""
label: 处理模式
input_method: Dropdown
options:
    - 快速模式
    - 标准模式
    - 高质量模式
description: 选择图片处理的质量模式
"""
self.process_mode: str = "标准模式"

必填属性：

label - 参数显示名称
input_method - 固定为 "Dropdown"
options - 选项列表（至少1个）
description - 参数说明

12. DatePicker (日期选择)

DatePicker 日期选择

用于选择日期的日期选择器。

"""
label: 截止日期
input_method: DatePicker
format: yyyy-MM-dd
min: 2020-01-01
max: 2030-12-31
description: 选择数据处理的截止日期
"""
self.end_date: str = "2024-12-31"

必填属性：

label - 参数显示名称
input_method - 固定为 "DatePicker"
format - 日期格式（如 yyyy-MM-dd）
min - 最小日期
max - 最大日期
description - 参数说明

13. TimePicker (时间选择)

TimePicker 时间选择

用于选择时间的时间选择器。

"""
label: 执行时间
input_method: TimePicker
format: HH:mm
min: 00:00
max: 23:59
description: 选择脚本执行的时间
"""
self.execution_time: str = "12:00"

必填属性：

label - 参数显示名称
input_method - 固定为 "TimePicker"
format - 时间格式（如 HH:mm）
min - 最小时间
max - 最大时间
description - 参数说明

14. Slider (滑块选择)

Slider 滑块选择

用于通过滑块选择数值的滑块控件。

"""
label: 透明度
input_method: Slider
unit: %
max: 100
min: 0
precision: 0
divisions: 100
description: 调整水印的透明度
"""
self.opacity: float = 50.0

必填属性：

label - 参数显示名称
input_method - 固定为 "Slider"
unit - 数值单位
max - 最大值
min - 最小值
precision - 小数位数
divisions - 滑块分割数量
description - 参数说明

15. PasswordInput (密码输入)

PasswordInput 密码输入

用于输入密码的密码输入框，输入内容会被隐藏。

"""
label: 文件密码
input_method: PasswordInput
validation: ^.{6,}$
validation_message: 密码至少6个字符
description: 输入加密文件的密码
"""
self.file_password: str = ""

必填属性：

label - 参数显示名称
input_method - 固定为 "PasswordInput"
validation - 正则表达式验证
validation_message - 验证失败提示
description - 参数说明

完整示例

以下是一个完整的快格式脚本示例，展示了图片批量处理的功能：

# coding=utf-8
"""
kuai: 1.0
python_version:
    - 3.8+
os:
    - Windows
packages:
    - Pillow
    - pathlib
name: 图片批量处理工具
description: 批量调整图片尺寸、格式转换和添加水印
input_description: 输入多张图片文件（支持JPG、PNG格式）
output_description: 输出处理后的图片文件到指定目录
"""

import argparse
import json
from urllib.parse import quote, unquote
from PIL import Image
from pathlib import Path


class Params:
    """
    说明: 启动参数（实例属性）
    """

    def __init__(self):
        """
        label: 输入图片文件
        input_method: MultiFilePicker
        file_types:
            - jpg
            - jpeg
            - png
        min_files: 1
        max_files: 50
        description: 选择要批量处理的图片文件
        """
        self.input_files: [str] = []

        """
        label: 输出目录
        input_method: SingleDirectoryPicker
        description: 选择处理后图片的保存目录
        """
        self.output_dir: str = ""

        """
        label: 输出格式
        input_method: Radio
        options:
            - JPEG
            - PNG
            - WebP
        description: 选择输出图片的格式
        """
        self.output_format: str = "JPEG"

        """
        label: 图片宽度
        input_method: IntInput
        unit: 像素
        max: 4096
        min: 100
        description: 设置输出图片的宽度（高度自动等比缩放）
        """
        self.target_width: int = 800

        """
        label: 图片质量
        input_method: Slider
        unit: %
        max: 100
        min: 10
        precision: 0
        divisions: 90
        description: 设置输出图片的质量（仅对JPEG格式有效）
        """
        self.quality: float = 85.0

        """
        label: 添加水印
        input_method: ToggleSwitch
        description: 是否在图片上添加文字水印
        """
        self.add_watermark: bool = False

        """
        label: 水印文字
        input_method: SingleLineTextInput
        max_length: 30
        min_length: 1
        validation: ^[\u4e00-\u9fa5a-zA-Z0-9\s]+$
        validation_message: 水印文字只能包含中文、英文、数字和空格
        description: 输入要添加的水印文字内容
        """
        self.watermark_text: str = "水印"

    def load(self, _params):
        for key, value in _params.items():
            if hasattr(self, key):
                setattr(self, key, value)


# 全局参数实例
params = Params()


def param():
    parser = argparse.ArgumentParser()
    parser.add_argument('json_string', type=str)
    args = parser.parse_args()
    if args.json_string is not None:
        decoded_json_string = unquote(args.json_string)
        params.load(json.loads(decoded_json_string))


def process_images():
    """处理图片的主要函数"""
    for input_file in params.input_files:
        # 图片处理逻辑
        pass


if __name__ == "__main__":
    param()
    process_images()

最佳实践

1. 参数设计原则

💡 设计建议

标签一致性：所有参数的 label 长度尽量保持一致，通常控制在2-8个字符。

描述清晰：description 应该简洁明了地说明参数的作用和注意事项。

默认值合理：为参数设置合理的默认值，让用户能够快速开始使用。

2. 文件类型规范

文件扩展名使用小写，不包含点号，如 jpg 而不是 .jpg
常见文件类型：txt, csv, xlsx, json, jpg, png, pdf
合理限制文件数量，避免性能问题

3. 验证规则

使用标准的正则表达式进行输入验证
提供友好的验证失败提示信息
常用验证模式：邮箱、手机号、身份证、密码强度等

4. 数值范围设置

设置合理的最小值和最大值，防止异常输入
浮点数精度根据实际需求设置，避免过多小数位
滑块的分割数量要适中，通常50-200之间

5. 代码结构建议

# 推荐的代码结构
# 1. 导入必要的模块
import argparse
import json
from urllib.parse import unquote

# 2. 定义Params类
class Params:
    def __init__(self):
        # 参数定义
        pass
    
    def load(self, _params):
        # 参数加载逻辑
        pass

# 3. 创建全局参数实例
params = Params()

# 4. 参数解析函数
def param():
    # 解析逻辑
    pass

# 5. 主要业务逻辑函数
def main_process():
    # 业务逻辑
    pass

# 6. 主程序入口
if __name__ == "__main__":
    param()
    main_process()

版本说明

当前版本特性 (v1.0)

✅ 已支持功能

• 15种完整的参数输入类型
• 完整的元数据规范
• 严格的参数验证
• 自动依赖包管理

⚠️ 当前限制

• 所有参数属性均为必填
• 不支持条件显示/隐藏参数
• 不支持参数分组
• 不支持自定义验证函数

版本发展路线图

v1.1：支持可选参数属性
v1.2：参数分组和条件显示
v1.3：自定义验证和高级控件
v2.0：多文件项目支持

📞 技术支持

如果您在使用快格式过程中遇到问题，或有新的功能建议，欢迎联系我们的技术支持团队。我们将持续改进快格式标准，为开发者提供更好的体验。

📋 当前版本说明 [v1.0]

元数据规范

参数类型详解

⚠️ 重要提示

1. Radio (单选参数)

Radio 单选

必填属性：

2. ToggleSwitch (开关参数)

ToggleSwitch 开关

必填属性：

3. Checkbox (多选参数)

Checkbox 多选

必填属性：

4. IntInput (整数输入)

IntInput 整数

必填属性：

5. FloatInput (浮点数输入)

FloatInput 浮点数

必填属性：

6. SingleLineTextInput (单行文本输入)

SingleLineTextInput 单行文本

必填属性：

7. MultiLineTextInput (多行文本输入)

MultiLineTextInput 多行文本

必填属性：

8. SingleFilePicker (单文件选择)

SingleFilePicker 单文件

必填属性：

9. MultiFilePicker (多文件选择)

MultiFilePicker 多文件

必填属性：

10. SingleDirectoryPicker (目录选择)

SingleDirectoryPicker 目录选择

必填属性：

11. Dropdown (下拉选择)

Dropdown 下拉选择

必填属性：

12. DatePicker (日期选择)

DatePicker 日期选择

必填属性：

13. TimePicker (时间选择)

TimePicker 时间选择

必填属性：

14. Slider (滑块选择)

Slider 滑块选择

必填属性：

15. PasswordInput (密码输入)

PasswordInput 密码输入

必填属性：

完整示例

最佳实践

1. 参数设计原则

💡 设计建议

2. 文件类型规范

3. 验证规则

4. 数值范围设置

5. 代码结构建议

版本说明

当前版本特性 (v1.0)

✅ 已支持功能

⚠️ 当前限制

版本发展路线图

📞 技术支持