README

v2版本变更日志

此小部件的v2版本与v1版本不完全兼容。

移除了jsVarName属性。
移除了scriptPosition属性。
添加了JS模块。
添加了mapOptionScript属性。
修复了一些小错误。

概述

此小部件封装了[OpenLayers 3] (http://openlayers.org/)库，以便在Yii 2中方便使用。它自动注册OpenLayers库并在目标div上创建地图。

小部件还简化了地图的复杂配置选项，包括

快捷机制将PHP结构转换为JavaScript。
处理要应用于地图的额外JavaScript代码。

安装

Composer

这是安装小部件的首选方式。只需将sibilino/yii2-openlayers添加到您的Yii 2应用程序的composer.json文件中，然后像往常一样执行Composer更新。

"require": {
	"sibilino/yii2-openlayers": "*"
}

手动安装

如果您无法或不想使用Composer，则必须手动创建小部件文件夹，然后配置您的Yii 2应用程序来自动加载小部件类。

首先，在您的Yii 2应用程序的vendor子文件夹中创建文件夹结构sibilino/yii2-openlayers/widget。

然后，下载小部件.zip文件，并将其widget子文件夹中的内容提取到您在上一步骤中创建的文件夹中。

接下来，编辑您的应用程序的config文件（通常是config/main.php或config/web.php），并添加以下别名

[
	//...
	'aliases' => [
		//...
		'@sibilino/yii2/openlayers' => '@vendor/sibilino/yii2-openlayers/widget',
		//...
	],
	//...
]

调用小部件的任何类时，请记住使用命名空间sibilino\yii2\openlayers

use sibilino\yii2\openlayers\OpenLayers;
use sibilino\yii2\openlayers\OL;

用法

在您的视图中，像往常一样输出小部件方法。OpenLayers Map()的选项可以在mapOptions中指定。小部件将自动发布OpenLayers库并输出接收地图的div。

配置

小部件支持以下配置选项（实际OpenLayers.js选项在mapOptions数组中）

id：小部件和生成的容器div的id。
options：容器div的HTML选项数组。
mapOptions：要传递给JavaScript OpenLayers Map()构造函数的配置数组。如果未指定，则自动处理target选项。其结构和可用选项与[OpenLayers 3库] (http://openlayers.org/)支持的相同。以下是一些简化功能，如下所述。
mapOptionScript：要注册的JavaScript文件的URL，在olwidget.js模块之后注册。可以是数组，以注册多个脚本。脚本可以通过在sibilino.olwidget.mapOptions[mapId]中设置它们来注册具有id mapId的地图的选项。下面将详细介绍。

指定地图选项

OpenLayers地图选项的问题在于它们需要复杂的JavaScript结构。有两种方法可用

在PHP中管理配置，然后将其转换为JavaScript。
直接在JavaScript中管理配置。

如果您的地图配置相对简单，并且主要依赖于您PHP应用程序中已经存在的数据结构，那么方法#1可能更容易。此小部件包含OL类，可以促进PHP到JavaScript的转换。以下是详细信息。

当您的配置开始变得复杂时，OL类开始显示其局限性，您必须使用JsExpressions，这不再容易嵌套，基本上意味着您又开始编写纯JavaScript。在这种情况下，方法#2可能是必要的。此小部件提供了一个JavaScript模块，可以轻松地将您的配置从脚本文件传递到创建的地图。以下是详细信息。

混合使用这两种方法可能是轻松定义您的地图配置的最佳方式。

PHP数组形式的地图选项

想法是将OpenLayers的JavaScript选项定义为一个PHP数组，当JavaScript需要new ol.something()时，使用new OL('something')，并让小部件自动管理到JavaScript的转换。

例如

use sibilino\yii2\openlayers\OpenLayers;
use sibilino\yii2\openlayers\OL;
use yii\web\JsExpression;
//...

echo OpenLayers::widget([
	'id' => 'test',
	'mapOptions' => [
		'layers' => [
			// Easily generate JavaScript "new ol.layer.Tile()" using the OL class
			new OL('layer.Tile', [
				'source' => new OL('source.MapQuest', [
					'layer' => 'sat',
				]),
			]),
		],
		// Using a shortcut, we can skip the OL('View' ...)
		'view' => [
			// Of course, the generated JS can be customized with JsExpression, as usual
			'center' => new JsExpression('ol.proj.transform([37.41, 8.82], "EPSG:4326", "EPSG:3857")'),
			'zoom' => 4,
		],
	],
]);?>

有关配置详细信息，请参阅下一节。

有关OpenLayers配置的详细信息，请参阅[官方OpenLayers 3文档]（http://openlayers.org/）。

简化地图选项

传递JavaScript和OL类

OpenLayers的许多选项必须通过“ol”命名空间下的JavaScript对象实例来指定。这通常需要一个包含字符串，如new ol.layer.Tile()（对于Tile对象），并且需要进一步复杂化以将配置传递给构造的对象。为了避免这种繁琐的表示法，可以使用OL类。其构造函数接受一个类名，可以包含命名空间信息，以及一个用于类名构造函数的选项数组。例如

$olObject = new OL('source.MapQuest', ['layer' => 'sat']);

每个OL对象都表现得像一个JsExpression，它将生成指定类名的JavaScript代码，并使用选项进行实例化。在示例的情况下，生成的代码将是

new ol.source.MapQuest({layer:"sat"})

最终，这允许PHP配置数组创建得就像所需的JavaScript配置对象一样，但在需要new ol.Something()时使用new OL('Something')。

使用快捷字符串指定选项

当指定mapOptions['view']或mapOptions['layers']数组时，您可以使用字符串指定某些对象，而不是创建相应的OL实例。支持此类字符串快捷方式的选项是mapOptions['view']和mapOptions['layers']中的任何图层。例如

'mapOptions' => [
	'layers' => [
		'Tile' => [ // The layer type as a string, no need for new OL('layer.Tile' ...)
			'source' => new OL('source.MapQuest', [
				'layer' => 'sat',
			])
		],
	],
	'view' => [ // The 'view' option does not require new OL('View' ...) either
		'center' => new JsExpression('ol.proj.transform([37.41, 8.82], "EPSG:4326", "EPSG:3857")'),
		'zoom' => 4,
	],
],

此外，无论何时使用类型字符串定义了图层，源也可以使用类型字符串指定。例如

'mapOptions' => [
	'layers' => [
		// Again no need for OL('ol.source.OSM'), but no configuration can be passed to the OSM object in this case.
		'Tile' => 'OSM',
	],
],

JavaScript形式的地图选项

小部件发布了一个作为全局作用域中的sibilino.olwidget公开的JavaScript模块。可以通过sibilino.olwidget.mapOptions数组中与mapId键关联的对象指定创建具有id mapId的地图的选项。例如

var select = new ol.interaction.Select({...});
sibilino.olwidget.mapOptions['mainMap'] = {
    layers: [
    	new ol.layer.Vector({...})
    ],
    interactions: ol.interaction.defaults().extend([select])
}

您可以通过设置其Web可访问URL在PHP小部件的mapOptionScript属性中注册此类脚本。例如

echo OpenLayers::widget([
    'id' => 'mainMap',
    'mapOptionScript' => '@web/js/yourscript.js',
    'mapOptions' => [
        // Put your PHP-generated options here.
        // These options will be merged with the ones in yourscript.js.
        // For example:
        'layers' => [
                'Tile' => [
                    'source' => new OL('source.MapQuest', [
                        'layer' => $selectedLayer,
                    ]),
                ],
                'Vector' => [
                    'source' => new OL('source.Cluster', [
                        'distance' => 30,
                        'source' => new OL('source.Vector', [
                            'features' => $features,
                        ]),
                    ]),
                ],
        ],
        // ...
    ],
    //...
]);

或者，您可以从任何在模块脚本之后加载的JavaScript代码中访问sibilino.olwidget模块。为了确保正确的脚本顺序，您可以使用对sibilino\yii2\openlayers\OLModuleBundle的依赖关系。例如

$view->registerJsFile($script, ['depends' => OLModuleBundle::className()]);

访问地图对象

如果您有需要在您的PHP代码中与由小部件创建的地图对象一起工作的JavaScript代码，您可以使用sibilino.olwidget.getMapById(mapId)找到它。此函数返回由小部件创建的具有id mapId的地图对象。例如

// Assuming the PHP widget was given the id "mainMap"
var map = sibilino.olwidget.getMapById("mainMap");

sibilino / yii2-openlayers

维护者

详细信息