diff --git a/src/ol/View.js b/src/ol/View.js index d2ab683f81..bbc373067a 100644 --- a/src/ol/View.js +++ b/src/ol/View.js @@ -129,9 +129,14 @@ import {createMinMaxResolution} from './resolutionconstraint.js'; * @property {boolean} [smoothResolutionConstraint=true] If true, the resolution * min/max values will be applied smoothly, i. e. allow the view to exceed slightly * the given resolution or zoom bounds. - * @property {boolean} [constrainOneAxis=false] If true, the extent constraint can - * be exceeded along one but not both axes, allowing the whole extent to be visible - * on the map. + * @property {boolean} [showFullExtent=false] Allow the view to be zoomed out to + * show the full configured extent. By default, when a view is configured with an + * extent, users will not be able to zoom out so the viewport exceeds the extent in + * either dimension. This means the full extent may not be visible if the viewport + * is taller or wider than the aspect ratio of the configured extent. If + * showFullExtent is true, the user will be able to zoom out so that the viewport + * exceeds the height or width of the configured extent, but not both, allowing the + * full extent to be shown. * @property {import("./proj.js").ProjectionLike} [projection='EPSG:3857'] The * projection. The default is Spherical Mercator. * @property {number} [resolution] The initial resolution for the view. The @@ -1614,8 +1619,8 @@ export function createResolutionConstraint(options) { const smooth = options.smoothResolutionConstraint !== undefined ? options.smoothResolutionConstraint : true; - const oneAxis = - options.constrainOneAxis !== undefined ? options.constrainOneAxis : false; + const showFullExtent = + options.showFullExtent !== undefined ? options.showFullExtent : false; const projection = createProjection(options.projection, 'EPSG:3857'); const projExtent = projection.getExtent(); @@ -1634,10 +1639,10 @@ export function createResolutionConstraint(options) { if (options.constrainResolution) { resolutionConstraint = createSnapToResolutions(resolutions, smooth, - !constrainOnlyCenter && extent, oneAxis); + !constrainOnlyCenter && extent, showFullExtent); } else { resolutionConstraint = createMinMaxResolution(maxResolution, minResolution, smooth, - !constrainOnlyCenter && extent, oneAxis); + !constrainOnlyCenter && extent, showFullExtent); } } else { // calculate the default min and max resolution @@ -1683,10 +1688,10 @@ export function createResolutionConstraint(options) { if (options.constrainResolution) { resolutionConstraint = createSnapToPower( zoomFactor, maxResolution, minResolution, smooth, - !constrainOnlyCenter && extent, oneAxis); + !constrainOnlyCenter && extent, showFullExtent); } else { resolutionConstraint = createMinMaxResolution(maxResolution, minResolution, smooth, - !constrainOnlyCenter && extent, oneAxis); + !constrainOnlyCenter && extent, showFullExtent); } } return {constraint: resolutionConstraint, maxResolution: maxResolution, diff --git a/src/ol/resolutionconstraint.js b/src/ol/resolutionconstraint.js index 73dec32ace..e0fa04e6b7 100644 --- a/src/ol/resolutionconstraint.js +++ b/src/ol/resolutionconstraint.js @@ -16,14 +16,14 @@ import {clamp} from './math.js'; * @param {number} resolution Resolution * @param {import("./extent.js").Extent=} maxExtent Maximum allowed extent. * @param {import("./size.js").Size} viewportSize Viewport size. - * @param {boolean} oneAxis Whether we can exceed extent constraint along one axis but not both. + * @param {boolean} showFullExtent Whether to show the full extent. * @return {number} Capped resolution. */ -function getViewportClampedResolution(resolution, maxExtent, viewportSize, oneAxis) { +function getViewportClampedResolution(resolution, maxExtent, viewportSize, showFullExtent) { const xResolution = getWidth(maxExtent) / viewportSize[0]; const yResolution = getHeight(maxExtent) / viewportSize[1]; - if (oneAxis) { + if (showFullExtent) { return Math.min(resolution, Math.max(xResolution, yResolution)); } return Math.min(resolution, Math.min(xResolution, yResolution)); @@ -57,10 +57,10 @@ function getSmoothClampedResolution(resolution, maxResolution, minResolution) { * @param {Array} resolutions Resolutions. * @param {boolean=} opt_smooth If true, the view will be able to slightly exceed resolution limits. Default: true. * @param {import("./extent.js").Extent=} opt_maxExtent Maximum allowed extent. - * @param {boolean=} opt_oneAxis If true, can exceed extent constraint along one axis but not both. Default: false. + * @param {boolean=} opt_showFullExtent If true, allows us to show the full extent. Default: false. * @return {Type} Zoom function. */ -export function createSnapToResolutions(resolutions, opt_smooth, opt_maxExtent, opt_oneAxis) { +export function createSnapToResolutions(resolutions, opt_smooth, opt_maxExtent, opt_showFullExtent) { return ( /** * @param {number|undefined} resolution Resolution. @@ -74,7 +74,7 @@ export function createSnapToResolutions(resolutions, opt_smooth, opt_maxExtent, const maxResolution = resolutions[0]; const minResolution = resolutions[resolutions.length - 1]; const cappedMaxRes = opt_maxExtent ? - getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_oneAxis) : + getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_showFullExtent) : maxResolution; // during interacting or animating, allow intermediary values @@ -106,10 +106,10 @@ export function createSnapToResolutions(resolutions, opt_smooth, opt_maxExtent, * @param {number=} opt_minResolution Minimum resolution. * @param {boolean=} opt_smooth If true, the view will be able to slightly exceed resolution limits. Default: true. * @param {import("./extent.js").Extent=} opt_maxExtent Maximum allowed extent. - * @param {boolean=} opt_oneAxis If true, can exceed extent constraint along one axis but not both. Default: false. + * @param {boolean=} opt_showFullExtent If true, allows us to show the full extent. Default: false. * @return {Type} Zoom function. */ -export function createSnapToPower(power, maxResolution, opt_minResolution, opt_smooth, opt_maxExtent, opt_oneAxis) { +export function createSnapToPower(power, maxResolution, opt_minResolution, opt_smooth, opt_maxExtent, opt_showFullExtent) { return ( /** * @param {number|undefined} resolution Resolution. @@ -121,7 +121,7 @@ export function createSnapToPower(power, maxResolution, opt_minResolution, opt_s function(resolution, direction, size, opt_isMoving) { if (resolution !== undefined) { const cappedMaxRes = opt_maxExtent ? - getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_oneAxis) : + getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_showFullExtent) : maxResolution; const minResolution = opt_minResolution !== undefined ? opt_minResolution : 0; @@ -155,10 +155,10 @@ export function createSnapToPower(power, maxResolution, opt_minResolution, opt_s * @param {number} minResolution Min resolution. * @param {boolean=} opt_smooth If true, the view will be able to slightly exceed resolution limits. Default: true. * @param {import("./extent.js").Extent=} opt_maxExtent Maximum allowed extent. - * @param {boolean=} opt_oneAxis If true, can exceed extent constraint along one axis but not both. Default: false. + * @param {boolean=} opt_showFullExtent If true, allows us to show the full extent. Default: false. * @return {Type} Zoom function. */ -export function createMinMaxResolution(maxResolution, minResolution, opt_smooth, opt_maxExtent, opt_oneAxis) { +export function createMinMaxResolution(maxResolution, minResolution, opt_smooth, opt_maxExtent, opt_showFullExtent) { return ( /** * @param {number|undefined} resolution Resolution. @@ -170,7 +170,7 @@ export function createMinMaxResolution(maxResolution, minResolution, opt_smooth, function(resolution, direction, size, opt_isMoving) { if (resolution !== undefined) { const cappedMaxRes = opt_maxExtent ? - getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_oneAxis) : + getViewportClampedResolution(maxResolution, opt_maxExtent, size, opt_showFullExtent) : maxResolution; const smooth = opt_smooth !== undefined ? opt_smooth : true; diff --git a/test/spec/ol/view.test.js b/test/spec/ol/view.test.js index 3d0bd026b0..4ec4a4bce6 100644 --- a/test/spec/ol/view.test.js +++ b/test/spec/ol/view.test.js @@ -393,10 +393,10 @@ describe('ol.View', function() { expect(constraint(1, 0, size)).to.be(1); }); - it('accepts extent and constrainOneAxis and uses the larger value', function() { + it('accepts extent and showFullExtent and uses the larger value', function() { const constraint = getConstraint({ extent: [0, 0, 4000, 6000], - constrainOneAxis: true + showFullExtent: true }); expect(constraint(1000, 0, size)).to.be(30);