1.12 输入与事件修饰符

12 分钟阅读

原文链接: https://developer.apple.com/documentation/swiftui/view-input-and-events

1.12 输入与事件修饰符

为视图提供动作，以响应用户输入和系统事件。

概述

使用输入与事件修饰符可以为各种各样的用户输入或系统事件配置并提供处理器。例如，你可以检测和控制焦点、响应视图出现与消失等生命周期事件、管理键盘快捷方式等等。

交互性

disabled(_:) — 添加一个条件，控制用户是否可以与该视图交互。
interactionActivityTrackingTag(_:) — 设置一个用于跟踪交互性的标签。

列表控件

swipeActions(edge:allowsFullSwipe:content:) — 为列表中的某一行添加自定义轻扫操作。
refreshable(action:) — 添加一个异步处理器，当用户发起请求（例如下拉刷新）时可以更新视图显示的数据。
selectionDisabled(_:) — 添加一个条件，控制用户是否可以选择该视图。

容器控件

swipeActions(edge:allowsFullSwipe:content:onPresentationChanged:) — 为列表或容器中的某一行添加自定义轻扫操作，并在这些操作显现或关闭时通知你。
swipeActionsContainer() — 协调容器中各行之间轻扫操作的关闭与互斥。

滚动控件

scrollPosition(_:anchor:) — 把一个滚动位置的绑定关联到该视图内的某个滚动视图。
scrollPosition(id:anchor:) — 关联一个绑定，当该视图内的滚动视图滚动时更新它。
defaultScrollAnchor(_:) — 关联一个锚点，用于控制默认应渲染滚动视图内容的哪个部分。
defaultScrollAnchor(_:for:) — 关联一个锚点，用于在特定情形下控制滚动视图的位置。
scrollTargetBehavior(_:) — 设置视图在指定轴上可滚动时的滚动行为。
scrollTargetLayout(isEnabled:) — 把最外层的布局配置为滚动目标布局。
scrollInputBehavior(_:for:) — 启用或停用使用特定输入时在可滚动视图中的滚动。
scrollTransition(_:axis:transition:) — 应用给定的过渡，当该视图在所属滚动视图的可见区域内出现和消失时，在过渡的各个阶段之间添加动画。
scrollTransition(topLeading:bottomTrailing:axis:transition:) — 应用给定的过渡，当该视图在所属滚动视图的可见区域内出现和消失时，在过渡的各个阶段之间添加动画。
onScrollGeometryChange(for:of:action:) — 添加一个动作，当由滚动的几何信息生成的值发生变化时执行。
onScrollTargetVisibilityChange(idType:threshold:_:) — 添加一个动作，调用时携带关于哪些视图会被视为可见的信息。
onScrollVisibilityChange(threshold:_:) — 添加一个动作，当视图越过被视为在屏幕上或不在屏幕上的阈值时调用。
onScrollPhaseChange(_:) — 添加一个动作，当层级中第一个滚动视图的滚动阶段发生变化时执行。

几何信息

onGeometryChange(for:of:action:) — 添加一个动作，当由几何代理生成的值发生变化时执行。
onGeometryChange3D(for:of:action:) — 返回一个新视图，它会在由 transform(proxy) 计算出的值发生变化时调用 action(value)，其中的 proxy 提供对视图三维几何属性的访问。
onInteractiveResizeChange(_:) — 添加一个动作，当所属窗口正在被交互式调整大小时执行。

点按与手势

onTapGesture(count:perform:) — 添加一个动作，当该视图识别到点按手势时执行。
onTapGesture(count:coordinateSpace:perform:) — 添加一个动作，当该视图识别到点按手势时执行，并把交互位置提供给该动作。
onTapGesture(count:coordinateSpace:inputKinds:perform:) — 添加一个动作，当该视图识别到点按手势时执行，并把交互位置提供给该动作。
onLongPressGesture(minimumDuration:maximumDistance:perform:onPressingChanged:) — 添加一个动作，当该视图识别到长按手势时执行。
onLongPressGesture(minimumDuration:maximumDistance:inputKinds:perform:onPressingChanged:) — 添加一个动作，当该视图识别到长按手势时执行。
onLongPressGesture(minimumDuration:perform:onPressingChanged:) — 添加一个动作，当该视图识别到长按手势时执行。
onLongTouchGesture(minimumDuration:perform:onTouchingChanged:) — 添加一个动作，当该视图识别到遥控器长触摸手势时执行。长触摸手势是指手指放在遥控器触摸表面上却没有真正按下的情况。
gesture(_:) — 把一个 NSGestureRecognizerRepresentable 附加到该视图上。
gesture(_:isEnabled:) — 以比该视图自身定义的手势更低的优先级，把手势附加到该视图上。
gesture(_:name:isEnabled:) — 以比该视图自身定义的手势更低的优先级，把手势附加到该视图上。
gesture(_:including:) — 以比该视图自身定义的手势更低的优先级，把手势附加到该视图上。
highPriorityGesture(_:including:) — 以比该视图自身定义的手势更高的优先级，把手势附加到该视图上。
highPriorityGesture(_:isEnabled:) — 以比该视图自身定义的手势更高的优先级，把手势附加到该视图上。
highPriorityGesture(_:name:isEnabled:) — 以比该视图自身定义的手势更高的优先级，把手势附加到该视图上。
simultaneousGesture(_:including:) — 把手势附加到该视图上，与视图自身定义的手势同时处理。
simultaneousGesture(_:isEnabled:) — 把手势附加到该视图上，与视图自身定义的手势同时处理。
simultaneousGesture(_:name:isEnabled:) — 把手势附加到该视图上，与视图自身定义的手势同时处理。
defersSystemGestures(on:) — 设置你希望自己的手势优先于系统手势的屏幕边缘。
onPencilDoubleTap(perform:) — 添加一个动作，在用户双击 Apple Pencil 之后执行。
onPencilSqueeze(perform:) — 添加一个动作，在用户捏压 Apple Pencil 时执行。
allowsWindowActivationEvents() — 把该视图层级中的手势配置为处理激活所属窗口的事件。
allowsWindowActivationEvents(_:) — 配置该视图层级中的手势是否可以处理激活所属窗口的事件。

键盘输入

onKeyPress(_:action:) — 当视图拥有焦点时，如果用户按下硬件键盘上的某个按键，则执行一个动作。
onKeyPress(phases:action:) — 当视图拥有焦点时，如果用户按下硬件键盘上的任意按键，则执行一个动作。
onKeyPress(_:phases:action:) — 当视图拥有焦点时，如果用户按下硬件键盘上的某个按键，则执行一个动作。
onKeyPress(characters:phases:action:) — 当视图拥有焦点时，如果用户按下硬件键盘上的一个或多个按键，则执行一个动作。
onKeyPress(keys:phases:action:) — 当视图拥有焦点时，如果用户按下硬件键盘上的一个或多个按键，则执行一个动作。
onModifierKeysChanged(mask:initial:_:) — 每当用户按下或松开硬件修饰键时执行一个动作。

键盘快捷方式

keyboardShortcut(_:) — 为被修改的控件指定一个键盘快捷方式。
keyboardShortcut(_:modifiers:) — 定义一个键盘快捷方式并把它指定给被修改的控件。
keyboardShortcut(_:modifiers:localization:) — 定义一个键盘快捷方式并把它指定给被修改的控件。
modifierKeyAlternate(::) — 构建一个视图，当用户按下给定集合所指示的修饰键时，用它替代被修改的视图。

手部交互

handGestureShortcut(_:isEnabled:) — 为被修改的控件指定一个手势快捷方式。
handPointerBehavior(_:) — 设置用户与视图交互时手形指针的行为。
manipulable(coordinateSpace:operations:inertia:isEnabled:onChanged:) — 允许使用常见的手势操作该视图。
manipulable(transform:coordinateSpace:operations:inertia:isEnabled:onChanged:) — 对视图应用给定的三维仿射变换，并允许使用常见的手势操作它。
manipulable(using:) — 允许使用附加在另一个视图上的操作手势来操作该视图。
manipulationGesture(updating:coordinateSpace:operations:inertia:isEnabled:onChanged:) — 为该视图添加操作手势，但不允许该视图本身被操作。

悬停

onHover(perform:) — 添加一个动作，当用户把指针移入或移出视图框架时执行。
onContinuousHover(coordinateSpace:perform:) — 添加一个动作，当指针进入、在视图边界内移动以及离开视图边界时执行。
hoverEffect(_:) — 为该视图应用悬停效果。
hoverEffect(_:isEnabled:) — 为该视图应用悬停效果。
hoverEffect(_:in:isEnabled:) — 为该视图应用悬停效果，并可选地把它加入一个 HoverEffectGroup。
hoverEffect(in:isEnabled:body:) — 为该视图应用由给定闭包描述的悬停效果。
hoverEffectGroup() — 为后代视图上定义的所有效果添加一个隐式 HoverEffectGroup，这样当该视图或任何后代视图被悬停时，添加到子视图上的所有效果都会作为一个组一起激活。
hoverEffectGroup(_:) — 为后代视图上定义的所有效果添加一个 HoverEffectGroup，并在这个视图或任何后代视图被悬停时激活该组。
hoverEffectGroup(id:in:behavior:) — 为后代视图上定义的所有效果添加一个 HoverEffectGroup，并在这个视图或任何后代视图被悬停时激活该组。
hoverEffectDisabled(_:) — 添加一个条件，控制该视图是否可以显示悬停效果。
defaultHoverEffect(_:) — 设置该视图内各视图使用的默认悬停效果。
listRowHoverEffect(_:) — 请求包含该视图的列表行使用提供的悬停效果。
listRowHoverEffectDisabled(_:) — 请求停用包含该视图的列表行的悬停效果。

指针

pointerVisibility(_:) — 设置指针位于视图上方时的可见性。
pointerStyle(_:) — 设置指针位于视图上方时要显示的指针样式。

焦点

focused(_:equals:) — 把视图的焦点状态绑定到给定的状态值，从而修改这个视图。
focused(_:) — 把视图的焦点状态绑定到给定的布尔状态值，从而修改这个视图。
focusedValue(_:) — 为给定的对象类型设置焦点值。
focusedValue(::) — 注入一个你提供的值，供其他状态取决于焦点视图层级的视图使用，从而修改这个视图。
focusedSceneValue(_:) — 在场景范围内为给定的对象类型设置焦点值。
focusedSceneValue(::) — 注入一个你提供的值，供其他状态取决于获得焦点场景的视图使用，从而修改这个视图。
focusedObject(_:) — 创建一个新视图，把提供的对象暴露给其他状态取决于焦点视图层级的视图。
focusedSceneObject(_:) — 创建一个新视图，把提供的对象暴露给其他状态取决于活跃场景的视图。
prefersDefaultFocus(_:in:) — 指明在给定命名空间中该视图应默认接收焦点。
focusScope(_:) — 创建一个焦点范围，SwiftUI 用它来限制默认焦点偏好。
focusSection() — 指明应使用该视图的框架及其可聚焦后代群体来引导焦点移动。
focusable(_:) — 指明该视图是否可聚焦。
focusable(_:interactions:) — 指明该视图是否可聚焦，若可聚焦，还指明它支持哪些由焦点驱动的交互。
focusEffectDisabled(_:) — 添加一个条件，控制该视图是否可以显示焦点效果，例如默认的焦点环或悬停效果。
defaultFocus(::priority:) — 通过给给定的焦点状态绑定赋值，定义窗口中评估默认焦点的区域。
searchFocused(_:) — 把与最近的 searchable 修饰符关联的搜索框的焦点状态绑定到给定的布尔值，从而修改这个视图。
searchFocused(_:equals:) — 把与最近的 searchable 修饰符关联的搜索框的焦点状态绑定到给定的值，从而修改这个视图。

拷贝与粘贴

copyable(_:) — 指定在系统执行“拷贝”命令时要拷贝的项目列表。
cuttable(for:action:) — 指定一个动作，在系统执行“剪切”命令时把项目移动到剪贴板。
pasteDestination(for:action:validator:) — 指定一个动作，在系统执行“粘贴”命令时把经过验证的项目添加到视图中。
onCopyCommand(perform:) — 添加一个动作，以响应系统发出的“拷贝”命令。
onCutCommand(perform:) — 添加一个动作，以响应系统发出的“剪切”命令。
onPasteCommand(of:perform:) — 添加一个动作，以响应系统发出的“粘贴”命令。
onPasteCommand(of:validator:perform:) — 添加一个动作，以响应系统发出的“粘贴”命令，并处理由你验证过的项目。

拖放

dragConfiguration(_:) — 配置一次拖拽会话。
dragContainer(for:in:_:) — 一个包含可拖拽视图的容器，其拖拽负载基于多个被拖拽项目的标识符。
dragContainer(for:itemID:in:_:) — 一个包含可拖拽视图的容器。
dragContainerSelection(_:containerNamespace:) — 为拖拽容器提供多项目选择支持。
dragPreviewsFormation(_:) — 描述被拖拽的各个预览在视觉上是如何组合的。
draggable(_:) — 把该视图激活为拖放操作的源。
draggable(_:preview:) — 把该视图激活为拖放操作的源。
draggable(:containerNamespace::) — 把该视图激活为拖放操作的源，并可以提供一个可选的可标识负载，同时指定该视图所属拖拽容器的命名空间。
draggable(:id:containerNamespace::) — 把该视图激活为拖放操作的源，并可以提供一个可选负载，同时指定该视图所属拖拽容器的命名空间。
draggable(_:id:item:containerNamespace:) — 把该视图激活为拖放操作的源，并可以提供一个可选负载，同时指定该视图所属拖拽容器的命名空间。
draggable(_:item:containerNamespace:) — 把该视图激活为拖放操作的源，并可以提供一个可选的可标识负载，同时指定该视图所属拖拽容器的命名空间。
draggable(containerItemID:containerNamespace:) — 在拖拽容器内部把该视图激活为拖放操作的源。支持惰性拖拽容器。
dropConfiguration(_:) — 配置一次放置会话。
dropDestination(for:isEnabled:action:) — 定义一个拖放操作的目标，它提供放置操作提议，并用你指定的闭包处理被放置的内容。
dropPreviewsFormation(_:) — 描述放置时的各个预览是如何组合的。
itemProvider(_:) — 提供一个闭包，为某个特定数据元素给出拖拽表示。
onDrag(_:preview:) — 把该视图激活为拖放操作的源。
onDrag(_:) — 把该视图激活为拖放操作的源。
onDragSessionUpdated(_:) — 指定一个动作，在由 draggable(_:) 或其他拖拽修饰符激活的拖拽操作每次更新时执行。
onDrop(of:isTargeted:perform:) — 定义一个拖放操作的目标，用你指定的闭包处理被放置的内容。
onDrop(of:delegate:) — 使用你提供的代理所控制的行为，定义一个拖放操作的目标。
onDropSessionUpdated(_:) — 指定一个动作，在由 dropDestination(_:) 或其他放置修饰符激活的放置操作每次更新时执行。
springLoadingBehavior(_:) — 设置该视图的弹性加载行为。

重新排序

reorderContainer(for:isEnabled:move:) — 定义一个由可重排视图组成的容器。
reorderContainer(for:in:isEnabled:move:) — 定义一个由可重排视图组成的容器，并可用你指定的类型来标识区段。
reorderContainer(for:itemID:isEnabled:move:) — 定义一个由可重排视图组成的容器，并可用你指定的类型和键路径来标识项目。
reorderContainer(for:itemID:in:isEnabled:move:) — 定义一个由可重排视图组成的容器，并可用你指定的类型和键路径来标识项目，以及用某个类型来标识集合。

提交

onAssignedDocumentDidSubmit(_:) — 添加一个动作，在提交已分配文稿之后执行。
onAssignedDocumentDidWithdraw(_:) — 添加一个动作，在撤回已分配文稿的提交之后执行。
onAssignedDocumentWillSubmit(_:) — 添加一个动作，在提交已分配文稿之前执行。
onAssignedDocumentWillWithdraw(_:) — 添加一个动作，在撤回已分配文稿提交之前执行。
onSubmit(of:_:) — 添加一个动作，当用户向该视图提交值时执行。
submitScope(_:) — 阻止源自该视图的提交触发去调用视图层级中更高层提交修饰符所配置的提交动作。
submitLabel(_:) — 设置该视图的提交标签。

移动

onMoveCommand(perform:) — 添加一个动作以响应移动命令，例如用户在 Mac 键盘上按方向键，或在控制 Apple TV 时轻点 Siri Remote 的边缘。
moveDisabled(_:) — 添加一个条件，决定视图的视图层级是否可移动。

删除

onDeleteCommand(perform:) — 添加一个动作，以响应系统的“删除”命令，或者在视图拥有焦点时按下 ⌫（退格）或 ⌦（向前删除）键。
deleteDisabled(_:) — 添加一个条件，决定视图的视图层级是否可删除。

命令

pageCommand(value:in:step:) — 响应“上一页”或“下一页”命令，让某个值在区间中步进。
onExitCommand(perform:) — 设置一个动作，当视图拥有焦点并收到退出命令时触发。
onPlayPauseCommand(perform:) — 添加一个动作，以响应系统的“播放/暂停”命令。
onCommand(_:perform:) — 添加一个动作，以响应给定的选择器。

数码表冠

digitalCrownAccessory(_:) — 指定 Apple Watch 上数码表冠辅助视图的可见性。
digitalCrownAccessory(content:) — 在 Apple Watch 上把辅助视图放在数码表冠旁边。
digitalCrownRotation(_:from:through:sensitivity:isContinuous:isHapticFeedbackEnabled:onChange:onIdle:) — 通过更新指定的绑定来跟踪数码表冠的旋转。
digitalCrownRotation(_:onChange:onIdle:) — 通过更新指定的绑定来跟踪数码表冠的旋转。
digitalCrownRotation(detent:from:through:by:sensitivity:isContinuous:isHapticFeedbackEnabled:onChange:onIdle:) — 通过更新指定的绑定来跟踪数码表冠的旋转。
digitalCrownRotation(_:) — 通过更新指定的绑定来跟踪数码表冠的旋转。
digitalCrownRotation(_:from:through:by:sensitivity:isContinuous:isHapticFeedbackEnabled:) — 通过更新指定的绑定来跟踪数码表冠的旋转。

游戏控制器

handlesGameControllerEvents(matching:) — 指定当该视图或其某个后代视图拥有焦点时，应通过 GameController 框架传递哪些游戏控制器事件。
handlesGameControllerEvents(matching:withOptions:) — 指定当该视图或其某个后代视图拥有焦点时，应通过 GameController 框架传递哪些游戏控制器事件。

沉浸式空间

onImmersionChange(initial:_:) — 当应用的沉浸状态发生变化时执行一个动作。
onWorldRecenter(action:) — 添加一个动作，当使用数码表冠让视图重新居中时执行。
immersiveEnvironmentPicker(content:) — 添加菜单项，以便从媒体播放器的环境选择器中打开沉浸式空间。

立体空间

onVolumeViewpointChange(updateStrategy:initial:_:) — 添加一个动作，当立体空间的视点发生变化时执行。
supportedVolumeViewpoints(_:) — 指定立体空间中的窗口栏和装饰物支持哪些视点。

用户活动

userActivity(:element::) — 声明某种用户活动类型。
userActivity(:isActive::) — 声明某种用户活动类型。
onContinueUserActivity(_:perform:) — 注册一个处理器，以响应应用收到的用户活动。
handlesExternalEvents(preferring:allowing:) — 在场景已经打开的情况下，指定该视图所在场景处理哪些外部事件。

视图生命周期

onAppear(perform:) — 添加一个在该视图出现之前执行的动作。
onDisappear(perform:) — 添加一个在该视图消失之后执行的动作。
onChange(of:initial:_:) — 为该视图添加一个修饰符，在某个特定值变化时触发一个动作。
task(id:name:executorPreference:priority:file:line:_:) — 添加一个在该视图出现之前或某个指定值变化时执行的任务。
task(id:name:priority:file:line:_:) — 添加一个在该视图出现之前或某个指定值变化时执行的任务。
task(name:executorPreference:priority:file:line:action:) — 添加一个在该视图出现之前执行的异步任务。
task(name:priority:file:line:_:) — 添加一个在该视图出现之前执行的异步任务。

文件重命名

renameAction(_:) — 设置一个为重命名动作运行的闭包。

URL

onOpenURL(perform:) — 注册一个处理器，以响应应用收到的 URL。
onOpenURL(prefersInApp:) — 设置一个偏好使用应用内浏览器打开 URL 的 OpenURLAction。handler 闭包接收一个 URL 作为输入，并返回一个表示该动作结果的 OpenURLAction.Result。
widgetURL(_:) — 设置当用户点按小组件时要在所属应用中打开的 URL。

异步图像加载

asyncImageURLSession(_:) — 一个修饰符，为视图中包含的异步图像添加获取图像数据时要使用的 URL 会话。

发布者事件

onReceive(_:perform:) — 添加一个动作，当该视图检测到给定发布者发出的数据时执行。

命中测试

allowsHitTesting(_:) — 配置该视图是否参与命中测试操作。

内容形状

contentShape(_:eoFill:) — 定义用于命中测试的内容形状。
contentShape(::eoFill:) — 设置该视图的内容形状。

导入与导出

exportsItemProviders(_:onExport:) — 导出一个只读项目提供者，以供快捷指令、快速操作和服务使用。
exportsItemProviders(_:onExport:onEdit:) — 导出一个可读写项目提供者，以供快捷指令、快速操作和服务使用。
importsItemProviders(_:onImport:) — 允许从服务导入项目提供者，例如 macOS 上的“接续互通相机”。
exportableToServices(_:) — 导出项目以供快捷指令、快速操作和服务使用。
exportableToServices(_:onEdit:) — 导出可读写项目以供快捷指令、快速操作和服务使用。
importableFromServices(for:action:) — 允许从服务导入项目，例如 macOS 上的“接续互通相机”。

App Intent

appEntityIdentifier(_:) — 把一个 SwiftUI 视图与应用实体关联起来，使其内容能被 Apple Intelligence 和 Siri 发现。
appEntityIdentifier(forSelectionType:identifier:) — 把 SwiftUI 列表视图中的项目与应用实体关联起来，使它们能被 Apple Intelligence 和 Siri 发现。
appEntityUIElements(_:) — 向系统提供额外的上下文，使自定义视图的内容能被 Apple Intelligence 和 Siri 发现。
onAppIntentExecution(_:perform:) — 注册一个处理器，以响应应用收到的指定 App Intent。
shortcutsLinkStyle(_:) — 为视图层级中的 ShortcutsLink 设置给定的样式
siriTipViewStyle(_:) — 为视图层级中的 SiriTipView 设置给定的样式

相机

onCameraCaptureEvent(isEnabled:action:) — 用于注册由系统拍摄事件触发的动作。
onCameraCaptureEvent(isEnabled:defaultSoundDisabled:action:) — 用于注册由系统拍摄事件触发的动作。
onCameraCaptureEvent(isEnabled:defaultSoundDisabled:primaryAction:secondaryAction:) — 用于注册由系统拍摄事件触发的多个动作。
onCameraCaptureEvent(isEnabled:primaryAction:secondaryAction:) — 用于注册由系统拍摄事件触发的多个动作。
cameraAnchor(isActive:) — 指定应用哪个视图作为 Apple Vision Pro 二维 Persona 流的虚拟相机。

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)