企业官网建设流程全解析

• 前端
• 跨平台
• 桌面应用
• 移动开发

导读

CupertinoButton 是 Flet 框架中专门用于构建 iOS（Cupertino）设计风格按钮的核心控件。在需要为应用打造原汁原味的 iOS 交互体验、或通过adaptive=True让按钮随运行平台自动切换样式时，CupertinoButton 都是首选。阅读本文后，你将掌握 CupertinoButton 的完整属性体系、尺寸预设、事件回调、自适应机制，并能结合官方示例与 Flutter 底层实现写出可直接运行的 Flet 代码。

CupertinoButton 是什么

CupertinoButton（flet.CupertinoButton）是 Flet 对 FlutterCupertinoButtonWidget 的 Python 封装，位于 sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_button.py。它与 Material 风格的 button.md 控件并行，专门复刻 iOS 系统的按钮外观：圆角矩形、无阴影、按压时通过透明度变化（而非水波纹）反馈点击。

从源码结构看，CupertinoButton同时继承自LayoutControl（布局控件）和ActionControl（动作控件），因此在支持所有布局与通用属性（宽度、高度、边距、禁用状态等）的同时，也具备点击、长按等交互能力。它内部通过@control("CupertinoButton")装饰器注册，与 Flutter 侧的CupertinoButtonControl（见 packages/flet/lib/src/controls/cupertino_button.dart）一一对应，属性通过 JSON 协议同步到 Flutter 渲染层。

快速上手：官方示例解读

官方文档引用的完整示例位于 sdk/python/examples/controls/cupertino/cupertino_button/cupertino_button/main.py，运行后效果见下图的 macOS 截图：

import flet as ft def main(page: ft.Page): page.add( ft.SafeArea( content=ft.Column( controls=[ # 普通 CupertinoButton：浅灰背景 + 红色文字 ft.CupertinoButton( bgcolor=ft.CupertinoColors.LIGHT_BACKGROUND_GRAY, opacity_on_click=0.3, on_click=lambda _: print("Normal CupertinoButton clicked!"), content=ft.Text( value="Normal CupertinoButton", color=ft.CupertinoColors.DESTRUCTIVE_RED, ), ), # 填充样式：主色背景 + 黄色文字 + 圆角 15 ft.CupertinoButton( bgcolor=ft.Colors.PRIMARY, alignment=ft.Alignment.TOP_LEFT, border_radius=ft.BorderRadius.all(15), opacity_on_click=0.5, on_click=lambda _: print("Filled CupertinoButton clicked!"), content=ft.Text( "Filled CupertinoButton", color=ft.Colors.YELLOW, ), ), # 禁用状态 ft.CupertinoButton( bgcolor=ft.Colors.PRIMARY, disabled=True, alignment=ft.Alignment.TOP_LEFT, opacity_on_click=0.5, content=ft.Text("Disabled CupertinoButton"), ), # 自适应按钮：在 iOS 上渲染为 Cupertino 风格 ft.Button( adaptive=True, bgcolor=ft.CupertinoColors.SYSTEM_TEAL, content=ft.Row( tight=True, controls=[ ft.Icon(ft.Icons.FAVORITE, color="pink"), ft.Text("Button+adaptive"), ], ), ), ], ), ) ) if __name__ == "__main__": ft.run(main)

这个示例演示了 CupertinoButton 的三种典型状态：普通（浅灰背景）、填充（主色背景）与禁用（灰色不可交互），并顺带展示了与adaptive=True的通用按钮混用的场景——当应用需要在 iOS 与其它平台之间保持统一代码时，这种写法非常实用。

核心属性详解

以下属性均来自 cupertino_button.py 的字段定义，全部可直接在 Python 侧赋值。

内容与图标

在 Flutter 侧（cupertino_button.dart），icon与content会被组合进一个Row：仅图标时直接渲染图标，仅有文本时用DefaultTextStyle包裹以应用color。这让开发者可以用ft.Icon、ft.Text甚至更复杂的控件自由拼装按钮内容。

颜色与背景

尺寸、圆角与布局

opacity_on_click是 Cupertino 风格最有辨识度的行为——点击时整个按钮"变淡"而非显示涟漪。源码中它带有V.between(0.0, 1.0)校验，超出范围会抛出ValueError。

交互行为

尺寸预设：CupertinoButtonSize

CupertinoButtonSize是按钮的预设尺寸枚举（定义于同一源码文件），它整体影响最小尺寸、内边距、圆角与文字样式，而不是只改变一个维度：

在 Flutter 渲染层，该枚举被映射为CupertinoButtonSize.large / medium / small，直接透传给原生CupertinoButton.sizeStyle参数（cupertino_button.dart），因此其默认间距、字号与圆角与 iOS 系统按钮完全一致。

事件与聚焦控制

CupertinoButton支持四个事件回调，均为ControlEventHandler类型，在 cupertino_button.py 中定义：

其中on_click与on_long_press仅在控件未禁用（disabled=False）时才会触发——Flutter 侧在禁用时会把onPressed/onLongPress置为null（cupertino_button.dart）。

此外，控件还提供异步方法async def focus()，用于主动请求焦点，底层通过_invoke_method("focus")调用 Flutter 侧的FocusNode.requestFocus()（对应 cupertino_button.dart）。

async def my_button_action(page: ft.Page): btn = ft.CupertinoButton("确定", autofocus=True) page.add(btn) await btn.focus()

Flutter 底层实现与"类族"关系

从 cupertino_button.dart 的源码可以看出，Flet 对 Cupertino 按钮做了一个统一的实现层：根据控件类型自动选择三种 Flutter 构造函数——

• CupertinoFilledButton/FilledButton→CupertinoButton.filled（实心填充）
• CupertinoTintedButton/FilledTonalButton→CupertinoButton.tinted（淡色填充）
• 其它 →CupertinoButton（标准样式）

因此CupertinoButton、CupertinoFilledButton、CupertinoTintedButton共享同一套 Python 属性模型与渲染管线，本文讲解的属性同样适用于后两者。这三个控件的 Python 实现分别位于：

• cupertino_button.py
• cupertino_filled_button.py
• cupertino_tinted_button.py

与通用 Button 的关系：adaptive 自适应

Flet 的通用 button.md 控件提供adaptive参数：当adaptive=True且应用运行在 iOS 上时，ft.Button会被渲染为 Cupertino 风格；在其它平台则保持 Material 风格。官方示例的最后一行正是这种用法（ft.Button(adaptive=True, ...)），配合ft.CupertinoColors主题色即可让同一套代码在 iOS / Android / 桌面 / Web 上各显其形。

如果明确知道目标平台就是 iOS，则直接使用CupertinoButton更直观；需要跨平台自适应时，优先选择adaptive=True的通用按钮。

测试与验证

仓库中提供了 CupertinoButton 的集成测试，位于 test_cupertino_button.py，通过flet.testing.FletTestApp.assert_control_screenshot对ft.CupertinoButton("Click me")进行截图回归验证，确保控件渲染与 iOS 预期外观一致。另有基于官方示例的端到端测试 examples 版本。若你修改了按钮相关代码，可参照这些测试补充自己的验证用例。

实用配置参考

综合以上内容，一个覆盖多数场景的 CupertinoButton 配置如下：

import flet as ft ft.CupertinoButton( content=ft.Text("提交", color=ft.CupertinoColors.WHITE), icon=ft.Icons.SEND, icon_color=ft.CupertinoColors.WHITE, bgcolor=ft.CupertinoColors.ACTIVE_BLUE, disabled_bgcolor=ft.CupertinoColors.SYSTEM_GREY, size=ft.CupertinoButtonSize.MEDIUM, min_size=ft.Size(120, 40), padding=ft.Padding(16, 8, 16, 8), border_radius=ft.BorderRadius.all(10), opacity_on_click=0.5, alignment=ft.Alignment.CENTER, mouse_cursor=ft.MouseCursor.CLICK, autofocus=False, on_click=lambda e: print("clicked"), on_long_press=lambda e: print("long pressed"), )

小结

CupertinoButton 是 Flet 中实现 iOS 原生观感的核心控件：通过content/icon灵活组合内容，用bgcolor/color/border_radius/size控制外观，用opacity_on_click复刻 iOS 按压反馈，并通过on_click/on_long_press等事件完成交互闭环。它与CupertinoFilledButton、CupertinoTintedButton共享底层实现，也可通过通用 Button 的adaptive参数实现跨平台自适应。掌握这些能力后，你可以在 Flet 应用中轻松打造与 iOS 系统一致的原生质感按钮。

• 前端
• 跨平台
• 桌面应用
• 移动开发