PythonIDE Docs
中文
简体中文

布局 API

Stack、ScrollView、List/Form、Grid 和 GeometryReader。

本页查 Stack、ScrollView、List/Form、Grid、GeometryReader 和数据展示容器的签名。怎么选择布局结构见 布局系统

#分篇速查

分篇适合查询
堆叠布局 APIVStackHStackZStackLazyVStackLazyHStackSpacerDivider
滚动 APIScrollViewScrollViewReader、滚动方向、初始定位和锚点。
网格 APILazyVGridLazyHGridGridGridRowflexiblefixedadaptivegrid_item
几何与特殊布局 APIGeometryReaderViewThatFitsGroupOverlaySafeAreaInset
环境值 APIenvironment_valuepreferred_color_schemelocalelayout_direction、动态字体和文本环境。

#什么时候用

目标API
纵向/横向组合VStackHStack
层叠覆盖ZStackOverlay
自定义滚动内容ScrollViewLazyVStack
程序化滚动ScrollViewReader
卡片网格LazyVGridLazyHGridGrid
原生动态列表ListForEach
设置和编辑页FormSection
空状态和进度ContentUnavailableViewProgressView
大屏表格Table

#容器组合示例

同一页面可以同时使用 FormListLazyVGrid,但要让每个容器负责自己擅长的结构。

python
import appui

cards = [
    {"id": "a", "title": "Alpha"},
    {"id": "b", "title": "Beta"},
    {"id": "c", "title": "Gamma"},
]


def card_key(item):
    return item["id"]


def card_view(item):
    return (
        appui.Text(item["title"])
        .frame(max_width=appui.infinity, min_height=72)
        .background("secondarySystemBackground", corner_radius=8)
    )


def body():
    grid = appui.LazyVGrid(
        columns=[appui.adaptive(minimum=120)],
        spacing=12,
        content=[appui.ForEach(cards, row_builder=card_view, key=card_key)],
    )

    return appui.NavigationStack(
        appui.Form([
            appui.Section("Form", [
                appui.LabeledContent("Container", value="Form"),
            ]),
            appui.Section("Grid", [
                grid,
            ]),
        ]).navigation_title("Layout")
    )


appui.run(body)

#布局签名

API签名分类
VStackVStack(content: Optional[Sequence[View]] = None, alignment: str = 'center', spacing: Optional[float] = None)layout
HStackHStack(content: Optional[Sequence[View]] = None, alignment: str = 'center', spacing: Optional[float] = None)layout
ZStackZStack(content: Optional[Sequence[View]] = None, alignment: str = 'center')layout
LazyVStackLazyVStack(content: Optional[Sequence[View]] = None, alignment: str = 'center', spacing: Optional[float] = None)layout
LazyHStackLazyHStack(content: Optional[Sequence[View]] = None, alignment: str = 'center', spacing: Optional[float] = None)layout
ScrollViewScrollView(content: Optional[ViewChild] = None, axes: str = 'vertical', shows_indicators: bool = True, showsIndicators: Optional[bool] = None)layout
ScrollViewReaderScrollViewReader(content: Optional[ViewChild] = None, axes: str = 'vertical', shows_indicators: bool = True, scroll_to: Optional[str] = None, anchor: str = 'top', showsIndicators: Optional[bool] = None, scrollTo: Optional[str] = None, children: Optional[ViewChild] = None)layout
LazyVGridLazyVGrid(columns: Optional[Sequence[dict]] = None, content: Optional[Sequence[View]] = None, spacing: Optional[float] = None, children: Optional[Sequence[View]] = None)layout
LazyHGridLazyHGrid(rows: Optional[Sequence[dict]] = None, content: Optional[Sequence[View]] = None, spacing: Optional[float] = None, children: Optional[Sequence[View]] = None)layout
GridGrid(content: Optional[Sequence[View]] = None, alignment: str = 'center', horizontal_spacing: Optional[float] = None, vertical_spacing: Optional[float] = None, horizontalSpacing: Optional[float] = None, verticalSpacing: Optional[float] = None)layout
GridRowGridRow(content: Optional[Sequence[View]] = None, alignment: Optional[str] = None)layout
GeometryReaderGeometryReader(content: Optional[ViewChild] = None, on_change: Optional[Callable] = None, onChange: Optional[Callable] = None, children: Optional[ViewChild] = None, on_geometry: Optional[Callable] = None, onGeometry: Optional[Callable] = None)layout
ViewThatFitsViewThatFits(content: Optional[Sequence[View]] = None)layout
GroupGroup(content: Optional[Sequence[View]] = None)layout
OverlayOverlay(content: Optional[View] = None, overlay: Optional[View] = None, alignment: str = 'center')layout
SafeAreaInsetSafeAreaInset(edge: str = 'bottom', content: Optional[View] = None)layout
SpacerSpacer(min_length: Optional[float] = None, minLength: Optional[float] = None)layout
DividerDivider()layout

#数据容器

API签名分类
ListList(content: Optional[Sequence[View]] = None)collection
ForEachForEach(data: Any, row_builder: Optional[Callable] = None, key: Optional[Callable] = None, rowBuilder: Optional[Callable] = None, content: Optional[Callable] = None)collection
FormForm(content: Optional[Sequence[View]] = None)collection
SectionSection(content: Optional[ViewChild] = None, *, header: Optional[Union[str, View]] = None, footer: Optional[Union[str, View]] = None, children: Optional[ViewChild] = None, key: Optional[str] = None)collection
GroupBoxGroupBox(label: Optional[str] = None, content: Optional[ViewChild] = None, children: Optional[Sequence[View]] = None)collection
DisclosureGroupDisclosureGroup(label: str = '', is_expanded: Optional[bool] = None, content: Optional[ViewChild] = None, isExpanded: Optional[bool] = None, children: Optional[ViewChild] = None)collection
LabeledContentLabeledContent(label: str = '', value: Optional[str] = None, content: Optional[View] = None)collection
TableTable(data: Optional[Sequence[Dict[str, Any]]] = None, columns: Optional[Sequence[Dict[str, str]]] = None, on_select: Optional[Callable] = None, onSelect: Optional[Callable] = None)collection
ControlGroupControlGroup(label: str = '', content: Optional[Sequence[View]] = None, children: Optional[Sequence[View]] = None)control
ContentUnavailableViewContentUnavailableView(title: str = '', system_image: Optional[str] = None, description: Optional[str] = None, systemImage: Optional[str] = None)presentation
ProgressViewProgressView(label: Optional[str] = None, value: Optional[float] = None, total: float = 1.0)feedback
LinkLink(title: str = '', url: str = '')control
GaugeGauge(value: float = 0.0, min_value: float = 0.0, max_value: float = 1.0, label: str = '', minValue: Optional[float] = None, maxValue: Optional[float] = None)feedback
ShareLinkShareLink(item: str = '', subject: Optional[str] = None, message: Optional[str] = None)control
BadgeBadge(count: Optional[int] = None, text: Optional[str] = None)presentation
TimelineViewTimelineView(interval: float = 1.0, content: Optional[View] = None)feedback

#相邻 API 区别

API用法边界
List vs ScrollView动态行列表用 List;完全自定义滚动视觉才用 ScrollView
Form vs VStack设置和编辑页用 Form;普通局部排列用 VStack
LazyVGrid vs Grid卡片网格用 LazyVGrid;需要严格行列对齐用 Grid
Overlay vs .overlay(...)简单叠加优先用修饰符;需要显式节点时用 Overlay
ContentUnavailableView vs 空 Text空状态用 ContentUnavailableView,不要让列表区域空白。

#常见错误

错误后果修正
VStack(children=[...])构造参数不匹配VStack([...], spacing=...)
Section(content=List(...))嵌套滚动容器List([Section("Title", rows)])
动态列表没有 key搜索、删除后行身份不稳ForEach(data, row_builder=..., key=...)
用自绘卡片模拟设置页信息密度低,键盘和辅助功能差Form + Section
把重型媒体放进列表行滚动后可能空白或状态丢失媒体放稳定区域,控制项放 Form/List

#相关示例

文档用途
布局系统Stack、ScrollView、Grid、List/Form 的选择。
示例:待办列表完整 List、ForEach、搜索和稳定 id。
示例:仪表盘LazyVGrid 和卡片布局。