メインコンテンツまでスキップ

Viewport

A viewport typically refers to the visible area of a map or scene that is currently being displayed. Our ViewportManager offers an extensive high-level API for controlling a map's camera. It provides built-in states for following the location puck and showing an overview of a GeoJSON geometry. Transitions between states can be animated with one of the built-in transitions or with custom transitions.

To configure the ViewportManager, you can update its options. For example, if you want to take the safe area inset into account when calculating a viewport camera, you can set mapview.viewport.options.usesSafeAreaInsetsAsPadding to true.

Viewport status

At any given time, a ViewportStatus can be either of the followings:

  • Idle (camera is not updating)
  • Running in a state (an overview viewport or a viewport that is following a location's puck)
  • Transitioning to a new state
Note

Note that if you want to use other APIs to control the map's camera i.e MapboxMap.setCamera(to:), it's a good practice to make sure that the map's viewport is in an idle state.

Listen to viewport status's changes

You can get the current ViewportStatus by accessing ViewportManager.status. To get notified when the viewport status changed, you can provide your own implementation of ViewportStatusObserver and register it to the viewport manager using ViewportManager.addStatusObserver(_:)

Map's viewport manager will keep a strong reference to its status observers, therefore, when you no longer need to listen to viewport status's changes, you should unsubscribe using ViewportManager.removeStatusObserver(_:) to release this strong reference.

Note

Observers are notified of status changes asynchronously on the main queue. This means that by the time the notification is delivered, the status may have already changed again. This behavior is necessary to allow observers to trigger further transitions while avoiding out-of-order delivery of status changed notifications.

Viewport state

Overview Viewport

An OverviewViewportState shows a map camera that overviews a region defined by a geometry.

Map(initialViewport: .overview(
geometry: LineString(lineCoordinates),
geometryPadding: UIEdgeInsets(top: 40, left: 40, bottom: 40, right: 40))
)

Follow Puck Viewport

A FollowPuckViewportState shows a map camera that tracks user's location.

Note

Users must grant permission before an app can access information about their location. For more information about asking for the user’s location, see the User location guide.

Map(initialViewport: .followPuck(zoom: 16.35, bearing: .course, pitch: 45))

Viewport transitions

The Mapbox Maps SDK provides a way to smoothly transition between different viewport states, either with animations or none. This can enhance the user experience by providing a smooth visual transition between different map views.

The SDK provides 2 implementations of ViewportTransition: DefaultViewportTransition and ImmediateViewportTransition. To transition between viewport states, you first create an instance of the transition, and pass it to ViewportManager.transition(to:transition:completion:).

Immediate transition

Like the name suggested, ImmediateViewportTransition will transition immediately to the new viewport without any animation.

@State vart viewport = Viewport.camera()

Map(viewport: $viewport)
.onAppear {
viewport = .camera(zoom: 4)
}

Default transition

DefaultViewportTransition transitions between viewport states using an animation that offers cubic bezier easing. This is the default behavior of ViewportManager when transitioning between states.

You can use convenience method ViewportManager.makeDefaultViewportTransition(options:) to create an instance of this transition. Optionally you can set a maxDuration for the transition.

@State vart viewport = Viewport.camera()

Map(viewport: $viewport)
.onAppear {
withViewportAnimation(.default(maxDuration: 2)) {
viewport = .camera(zoom: 4)
}
}
Use camera animation before map is moved to window

Note that any usage of Camera Animator before the map view is moved to new window and the display link is created is invalid, all animators will be marked as completed immediately.

Customize Viewport state and transition

When developing the Mapbox Maps SDK, we emphasized the flexibility for developers to customize our maps, enabling you to achieve precisely tailored functionalities for your application. You can provide a custom implementation for ViewportState and ViewportTransition to handle advanced use cases not covered by the provided implementations.

Pre-warm viewport state's data source

To decrease delays when becoming current, states should generally pre-warm their data sources as soon as they are created. Keep alive only the states that are currently (or soon-to-be) needed to release unneeded resources, such as location services.

このpageは役に立ちましたか?