Toga Pack 布局系统详细解析

1. 布局基础属性

1.1 `direction` - 布局方向

作用：定义子元素的排列方向

可选值：

ROW：水平排列（默认）
COLUMN：垂直排列

python
import toga
from toga.style import Pack
from toga.style.pack import ROW, COLUMN

def build(app):
    # 水平排列的容器
    horizontal_box = toga.Box(style=Pack(direction=ROW, padding=10))
    btn1 = toga.Button("按钮1", style=Pack(padding=5))
    btn2 = toga.Button("按钮2", style=Pack(padding=5))
    horizontal_box.add(btn1)
    horizontal_box.add(btn2)
    
    # 垂直排列的容器  
    vertical_box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    btn3 = toga.Button("按钮3", style=Pack(padding=5))
    btn4 = toga.Button("按钮4", style=Pack(padding=5))
    vertical_box.add(btn3)
    vertical_box.add(btn4)
    
    # 主容器
    main_box = toga.Box(style=Pack(direction=COLUMN))
    main_box.add(horizontal_box)
    main_box.add(vertical_box)
    
    return main_box

1.2 `display` - 显示方式

作用：控制元素是否显示

可选值：

PACK：正常显示（默认）
NONE：隐藏元素（不占空间）

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    visible_btn = toga.Button("可见按钮", style=Pack(padding=5))
    hidden_btn = toga.Button("隐藏按钮", style=Pack(display=None, padding=5))
    
    box.add(visible_btn)
    box.add(hidden_btn)  # 这个按钮不会显示
    
    return box

1.3 `visibility` - 可见性

作用：控制元素可见性

可选值：

VISIBLE：可见（默认）
HIDDEN：隐藏（但仍占空间）

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    visible_btn = toga.Button("可见按钮", style=Pack(padding=5))
    # 隐藏但仍占空间的按钮
    hidden_btn = toga.Button("隐藏但占位", style=Pack(visibility='hidden', padding=5))
    another_btn = toga.Button("另一个按钮", style=Pack(padding=5))
    
    box.add(visible_btn)
    box.add(hidden_btn)  # 看不到但会占位置
    box.add(another_btn)
    
    return box

2. 对齐与分布属性

2.1 `align_items` - 交叉轴对齐

作用：在交叉轴上对齐子元素

可选值：

START：起始对齐
CENTER：居中对齐
END：末端对齐

python
from toga.style.pack import START, CENTER, END

def build(app):
    main_box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    # 起始对齐（顶部/左侧）
    start_box = toga.Box(
        style=Pack(direction=ROW, align_items=START, height=100, background_color='lightgray', padding=5)
    )
    start_box.add(toga.Button("Start", style=Pack(width=80, height=30)))
    
    # 居中对齐
    center_box = toga.Box(
        style=Pack(direction=ROW, align_items=CENTER, height=100, background_color='lightblue', padding=5)
    )
    center_box.add(toga.Button("Center", style=Pack(width=80, height=30)))
    
    # 末端对齐（底部/右侧）
    end_box = toga.Box(
        style=Pack(direction=ROW, align_items=END, height=100, background_color='lightgreen', padding=5)
    )
    end_box.add(toga.Button("End", style=Pack(width=80, height=30)))
    
    main_box.add(toga.Label("align_items 示例:", style=Pack(padding_bottom=5)))
    main_box.add(start_box)
    main_box.add(center_box)
    main_box.add(end_box)
    
    return main_box

2.2 `justify_content` - 主轴分布

作用：在主轴上分布子元素

可选值：

START：起始分布（默认）
CENTER：居中分布
END：末端分布

python
def build(app):
    main_box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    # 起始分布
    start_box = toga.Box(
        style=Pack(direction=ROW, justify_content=START, width=300, background_color='lightgray', padding=5)
    )
    for i in range(3):
        start_box.add(toga.Button(f"Btn{i}", style=Pack(width=60, margin=2)))
    
    # 居中分布
    center_box = toga.Box(
        style=Pack(direction=ROW, justify_content=CENTER, width=300, background_color='lightblue', padding=5)
    )
    for i in range(3):
        center_box.add(toga.Button(f"Btn{i}", style=Pack(width=60, margin=2)))
    
    # 末端分布
    end_box = toga.Box(
        style=Pack(direction=ROW, justify_content=END, width=300, background_color='lightgreen', padding=5)
    )
    for i in range(3):
        end_box.add(toga.Button(f"Btn{i}", style=Pack(width=60, margin=2)))
    
    main_box.add(toga.Label("justify_content 示例:", style=Pack(padding_bottom=5)))
    main_box.add(start_box)
    main_box.add(center_box)
    main_box.add(end_box)
    
    return main_box

3. 尺寸与弹性属性

3.1 `width` / `height` - 固定尺寸

作用：设置元素的固定宽度和高度

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    # 固定宽度的按钮
    fixed_btn = toga.Button(
        "固定宽度200", 
        style=Pack(width=200, height=40, background_color='lightblue', padding=5)
    )
    
    # 固定高度的按钮
    tall_btn = toga.Button(
        "固定高度80", 
        style=Pack(width=120, height=80, background_color='lightgreen', padding=5)
    )
    
    box.add(fixed_btn)
    box.add(tall_btn)
    
    return box

3.2 `flex` - 弹性布局

作用：在可用空间中按比例分配空间

注意：只在未设置明确宽高时生效

python
def build(app):
    box = toga.Box(style=Pack(direction=ROW, height=60, padding=10, background_color='gray'))
    
    # flex=1 的元素
    flex1_btn = toga.Button(
        "flex=1", 
        style=Pack(flex=1, margin=2, background_color='lightblue')
    )
    
    # flex=2 的元素（占用两倍空间）
    flex2_btn = toga.Button(
        "flex=2", 
        style=Pack(flex=2, margin=2, background_color='lightgreen')
    )
    
    # flex=1 的元素
    flex1_btn2 = toga.Button(
        "flex=1", 
        style=Pack(flex=1, margin=2, background_color='lightcoral')
    )
    
    box.add(flex1_btn)
    box.add(flex2_btn)
    box.add(flex1_btn2)
    
    return box

4. 间距属性

4.1 `margin` 系列 - 外边距

作用：设置元素的外边距

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=20, background_color='lightgray'))
    
    # 不同的外边距设置
    margins = [
        ("四周10px", {"margin": 10}),
        ("上下10px, 左右20px", {"margin": (10, 20)}),
        ("上10px, 右20px, 下30px, 左40px", {"margin": (10, 20, 30, 40)}),
        ("仅右边距50px", {"margin_right": 50}),
    ]
    
    for text, margin_style in margins:
        btn = toga.Button(
            text, 
            style=Pack(
                background_color='white', 
                padding=5,
                **margin_style
            )
        )
        box.add(btn)
    
    return box

5. 外观属性

5.1 `color` - 文字颜色

作用：设置文字颜色

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    colors = [
        ("红色文字", "red"),
        ("蓝色文字", "blue"),
        ("绿色文字", "green"),
        ("十六进制颜色", "#FF00FF"),
    ]
    
    for text, color in colors:
        label = toga.Label(
            text, 
            style=Pack(color=color, padding=5, font_size=14)
        )
        box.add(label)
    
    return box

5.2 `background_color` - 背景颜色

作用：设置背景颜色

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    backgrounds = [
        ("浅蓝背景", "lightblue"),
        ("浅绿背景", "lightgreen"),
        ("浅珊瑚色", "lightcoral"),
        ("黄色背景", "yellow"),
    ]
    
    for text, bg_color in backgrounds:
        btn = toga.Button(
            text, 
            style=Pack(
                background_color=bg_color, 
                padding=10, 
                margin=5,
                color='black'  # 确保文字可读
            )
        )
        box.add(btn)
    
    return box

6. 文本属性

6.1 `text_align` - 文本对齐

作用：设置文本水平对齐方式

python
from toga.style.pack import LEFT, RIGHT, CENTER, JUSTIFY

def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10, width=300))
    
    alignments = [
        ("左对齐文本", LEFT),
        ("居中对齐文本", CENTER),
        ("右对齐文本", RIGHT),
        ("两端对齐文本", JUSTIFY),
    ]
    
    for text, alignment in alignments:
        label = toga.Label(
            text, 
            style=Pack(
                text_align=alignment,
                padding=10,
                background_color='lightgray',
                width=280,
                margin=2
            )
        )
        box.add(label)
    
    return box

6.2 `text_direction` - 文本方向

作用：设置文本阅读方向

python
from toga.style.pack import LTR, RTL

def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    # 从左到右（默认）
    ltr_label = toga.Label(
        "从左到右文本 (LTR)", 
        style=Pack(text_direction=LTR, padding=10, background_color='lightblue')
    )
    
    # 从右到左
    rtl_label = toga.Label(
        "从右到左文本 (RTL)", 
        style=Pack(text_direction=RTL, padding=10, background_color='lightgreen')
    )
    
    box.add(ltr_label)
    box.add(rtl_label)
    
    return box

7. 字体属性

7.1 字体相关属性

作用：设置字体系列、样式、大小等

python
def build(app):
    box = toga.Box(style=Pack(direction=COLUMN, padding=10))
    
    # 字体系列
    font_family_label = toga.Label(
        "自定义字体: Arial", 
        style=Pack(font_family='Arial', font_size=14, padding=5)
    )
    
    # 字体大小
    font_size_label = toga.Label(
        "大号字体: 20pt", 
        style=Pack(font_size=20, padding=5)
    )
    
    # 字体粗细
    font_weight_label = toga.Label(
        "粗体文字", 
        style=Pack(font_weight='bold', padding=5)
    )
    
    # 字体样式
    font_style_label = toga.Label(
        "斜体文字", 
        style=Pack(font_style='italic', padding=5)
    )
    
    # 组合使用
    combined_label = toga.Label(
        "组合样式: 粗体+斜体+大号", 
        style=Pack(
            font_weight='bold', 
            font_style='italic', 
            font_size=16,
            padding=10,
            background_color='lightyellow'
        )
    )
    
    box.add(font_family_label)
    box.add(font_size_label)
    box.add(font_weight_label)
    box.add(font_style_label)
    box.add(combined_label)
    
    return box

8. 综合示例

下面是一个结合多种属性的完整示例：

python
import toga
from toga.style import Pack
from toga.style.pack import COLUMN, ROW, CENTER, START, END

def build(app):
    # 主容器 - 垂直布局
    main_box = toga.Box(style=Pack(direction=COLUMN, padding=20))
    
    # 标题
    title = toga.Label(
        "用户信息表单",
        style=Pack(
            text_align=CENTER,
            font_size=20,
            font_weight='bold',
            padding_bottom=20,
            color='navy'
        )
    )
    
    # 姓名行 - 水平布局
    name_box = toga.Box(style=Pack(direction=ROW, padding=10))
    name_label = toga.Label(
        "姓名:",
        style=Pack(width=80, padding_right=10, font_weight='bold')
    )
    name_input = toga.TextInput(
        style=Pack(flex=1, padding=8)
    )
    name_box.add(name_label)
    name_box.add(name_input)
    
    # 邮箱行 - 水平布局  
    email_box = toga.Box(style=Pack(direction=ROW, padding=10))
    email_label = toga.Label(
        "邮箱:",
        style=Pack(width=80, padding_right=10, font_weight='bold')
    )
    email_input = toga.TextInput(
        style=Pack(flex=1, padding=8)
    )
    email_box.add(email_label)
    email_box.add(email_input)
    
    # 按钮容器 - 水平布局，右对齐
    button_box = toga.Box(
        style=Pack(
            direction=ROW, 
            justify_content=END,
            padding_top=20
        )
    )
    
    cancel_btn = toga.Button(
        "取消",
        style=Pack(
            padding=15,
            margin_left=10,
            background_color='#e74c3c',
            color='white',
            width=100
        )
    )
    
    submit_btn = toga.Button(
        "提交",
        style=Pack(
            padding=15,
            margin_left=10,
            background_color='#3498db',
            color='white',
            width=100
        )
    )
    
    button_box.add(cancel_btn)
    button_box.add(submit_btn)
    
    # 将所有元素添加到主容器
    main_box.add(title)
    main_box.add(name_box)
    main_box.add(email_box)
    main_box.add(button_box)
    
    return main_box

def main():
    app = toga.App('综合示例', 'org.example.comprehensive', startup=build)
    return app

if __name__ == '__main__':
    main().main_loop()

重要注意事项

版本兼容性：确保使用的 Toga 版本与文档匹配
属性优先级：某些属性会相互影响，如 flex 只在未设置明确宽高时生效
布局嵌套：通过组合 ROW 和 COLUMN 方向可以创建复杂布局
调试技巧：给容器设置背景色可以直观看到布局边界

每个属性都可以单独使用或组合使用，通过不断实践可以掌握 Pack 布局系统的强大功能。

目录

1. 布局基础属性

1.1 direction - 布局方向

1.2 display - 显示方式

1.3 visibility - 可见性

2. 对齐与分布属性

2.1 align_items - 交叉轴对齐

2.2 justify_content - 主轴分布

3. 尺寸与弹性属性

3.1 width / height - 固定尺寸

3.2 flex - 弹性布局

4. 间距属性

4.1 margin 系列 - 外边距

5. 外观属性

5.1 color - 文字颜色

5.2 background_color - 背景颜色

6. 文本属性

6.1 text_align - 文本对齐

6.2 text_direction - 文本方向

7. 字体属性

7.1 字体相关属性

8. 综合示例

重要注意事项

1.1 `direction` - 布局方向

1.2 `display` - 显示方式

1.3 `visibility` - 可见性

2.1 `align_items` - 交叉轴对齐

2.2 `justify_content` - 主轴分布

3.1 `width` / `height` - 固定尺寸

3.2 `flex` - 弹性布局

4.1 `margin` 系列 - 外边距

5.1 `color` - 文字颜色

5.2 `background_color` - 背景颜色

6.1 `text_align` - 文本对齐

6.2 `text_direction` - 文本方向