README

Leaflet-wrapper for Yii2 PHP 框架

这是 Leaflet JavaScript 地图库的包装器，用于 Yii 2.0 PHP 框架。它是一个 Yii2 Widget，可以用来显示存储在 ActiveRecord 中的地理数据，并可以更新它。 Yii2-locator 可选包含搜索功能。它可以使用多个提供商，用于地图瓦片以及地理编码服务。

yii2-locator 的演示在此。

安装

安装 yii2-locator 的首选方法是使用 Composer。您可以将以下内容添加到您的 composer.json 文件的 require 部分

"sjaakp/yii2-locator": "*"

或者运行

composer require sjaakp/yii2-locator "*"

您也可以通过下载 ZIP 格式源代码手动安装 yii2-locator。

GeoJSON

Yii2-locator 处理 GeoJSON 格式的数据。一些数据库直接存储这些数据。其他数据库，如 MySQL 和 MariaDB，使用自己的格式来存储空间数据。我的 Yii2-spatial 扩展可以将 MySQL 格式转换为 GeoJSON，反之亦然。在这种情况下，模型应从 sjaakp\spatial\ActiveRecord 继承，而不是通常的 yii\db\ActiveRecord。

用法

一个典型的使用场景是这样的：假设我们有一个包含一些地理数据的数据库表，比如 tower 表。如果我们使用 MySQL 或 MariaDB，模型 Tower 的扩展如下

class Tower extends sjaakp\spatial\ActiveRecord    {
    public static function tableName()
    {
        return 'tower';
    }
    // ...
}

tower 表除了其他字段外，还有以下字段

location: POINT 塔的位置
mapcenter: POINT 地图的中心
mapzoom: int 地图的缩放级别

视图

在一个 yii2 视图中，显示一个塔的地图就像这样

<?php
use sjaakp\locator\Locator;
/**
 * @var app\models\Tower $model
 */
?>
...
<?php
    $map = Locator::begin([
        'height' => 480,
        // ... other options ...
    ]);
    
    $map->modelCenter($model, 'mapcenter'); // set the map's center
    
    $map->modelZoom($model, 'mapzoom'); // set the map's zoom level

    $map->modelFeature($model, 'location'); // place a marker at the tower's location

    Locator::end();
?>
...

索引

在 index 视图中显示所有塔的地图，可以这样实现

<?php
use sjaakp\locator\Locator;
/**
 * @var yii\data\ActiveDataProvider $dataProvider
 */
?>
...
<?php 
    $map = Locator::begin([
        'leafletOptions' => [
            'center' =>  [48.8, 2.3],   // Paris
            'zoom' => 5,
            // ... more options ...
        ],
    ]);

    $map->modelFeatures($dataProvider, 'location'); // provide the tower locations

    Locator::end();
?>
...

Active Locator

在一个 create 或 update 视图中，可以在表单中使用 Locator

<?php
use yii\widgets\ActiveForm;
use sjaakp\locator\Locator;
/**
 * @var app\models\Tower $model
 */
?>
...
<?php $form = ActiveForm::begin(); ?>
...
<?php
    $map = Locator::begin([
        // ... Locator options ...
    ]);
    
    $map->activeCenter($model, 'mapcenter'); // allow the map's center to be changed

    $map->activeZoom($model, 'mapzoom'); // allow the map's zoom level to be changed

    $map->activeMarker($model, 'location'); // allow the model's location to be changed

    $map->finder(); // add an interactive Search control to the map

    Locator::end();
?>
...
<?php ActiveForm::end(); ?>
...

方法

tileLayer($data) - 向地图添加瓦片。 $data: string|array: 瓦片提供商名称，或名称带选项。请参阅瓦片名称。返回： $this。
center($lat, $lng = null) - 设置地图的中心。 $lat 和 $lng 是纬度和经度， float 类型。 $lat 也可以是一个数组 [<lat>, <lng>]。返回： $this。
modelCenter($model, $attribute) - 将地图中心设置为$model中$attribute的值。这应该是一个GeoJSON Feature。返回：$this。
activeCenter($model, $attribute) - 创建一个ActiveField用于地图中心，与$model中$attribute的值（GeoJSON Feature）相关联。返回：$this。
zoom($z) - 设置地图的缩放级别。$z：integer。返回：$this。
modelZoom($model, $attribute) - 将地图的缩放级别设置为$model中$attribute的值。返回：$this。
activeZoom($model, $attribute) - 创建一个ActiveField用于地图的缩放级别，与$model中$attribute的值相关联。返回：$this。
feature($feature) - 向地图添加一个GeoJSON Feature。返回：$this。
modelFeature($model, $attribute) - 将$model中$attribute的值作为GeoJSON Feature添加到地图。返回：$this。
modelFeatures($dataProvider, $attribute) - 向地图添加多个GeoJSON features，由ActiveDataProvider $dataProvider提供，使用属性$attribute。返回：$this。
marker($lat = null, $lng = null, $options = [ ]) - 向地图添加标记。返回：$this。
- 如果$lat == null：标记出现在地图上第一次点击的位置。
- 如果$lat和$lng是float类型：这些是纬度和经度。
- 如果$lat是数组：[<latitude>, <longitude>]。
$options 标记的选项
- 'type'：标记的类型。如果没有设置：'Marker'。
- 其他选项传递给标记的构造函数。
modelMarker($model, $attribute, $options = [ ]) - 将标记的位置设置为$model中$attribute的值（GeoJSON Feature）。返回：$this。
activeMarker($model, $attribute, $options = [ ]) - 创建一个ActiveField用于标记位置，与$model中$attribute的值相关联。返回：$this。
geocoder($options) - 设置地图的地理编码器。返回：$this。
- $options是string：地理编码器提供者的[名称](#geocoder names)。
- $options是array：第一个是名称，其余是地理编码器选项。
finder($geocoder = null, $position = 'topright') - 使用$geocoder，在指定位置的地图上添加Search Control。返回：$this。
getVar() - 获取分配给Leaflet地图的JavaScript变量的名称。用于高级使用。

Locator是一个Yii2 Widget，因此继承其所有方法。

可链式

大多数Locator方法返回this，因此它们是可链式的。这意味着在视图中显示地图的最小代码可能是这样的

<?php
use sjaakp\locator\Locator;

...
<?php
    Locator::begin([
        // ... options ...
    ])->modelCenter($model, 'mapcenter')
        ->modelZoom($model, 'mapzoom')
        ->modelFeature($model, 'location')
        ->end();
?>
...

属性

$height int|string|false Locator元素的宽度。如果是int像素，如果是string任何有效的CSS值。如果是false，则不设置高度。注意，在这种情况下，必须通过其他方式设置高度，否则地图的高度将为零，并且将不可见。默认：400。
$tile string|array 首个瓦片层的名称或配置。默认值：'OpenStreetMap'。
$marker array 默认标记的类型和选项。默认值：[ 'type' => 'DotMarker' ]。
$options array 地图容器的HTML选项。使用此选项可以显式设置ID。默认值：[ ]（空数组）。
$leafletOptions array 地图的JavaScript 选项。默认值：[ ]（空数组）。
$cluster null|true|array MarkerClusterer的选项。如果null：不进行聚合。如果true：使用默认选项进行聚合。默认值：null。
$popup null|true|array 弹出窗口的选项。如果null：不显示弹出窗口。如果true：使用默认选项显示弹出窗口。默认值：null。
$scale null|int 在地图上显示比例尺控件。可以是null（不显示比例尺控件），SCALE_METRIC，SCALE_IMPERIAL或SCALE_BOTH。默认值：SCALE_METRIC。
$urlTemplate string 点击标记时使用的URL模板。如果未设置，则不执行任何操作。如果$popup已设置，则显示包含结果URL内容的弹出窗口。否则，将跳转到URL。'{xxx}'将被具有名称'xxx'的标记选项替换。典型用法：$urlTemplate = 'view/{id}'。默认值：null。
$fly bool 是否在找到标记后使用'fly-animation'。
$tileNamespace string 定义瓦片层的Tile*类的命名空间。使用此选项添加自己的瓦片层。

Locator是一个Yii2 Widget，因此继承其所有属性。

瓦片名称

Locator从瓦片提供商或地图提供商获取地图瓦片。瓦片由提供商的名称或包含名称作为第一个元素以及其余数组中选项的array标识。此值用于$tile属性和tileLayer()方法。一个地图可以有多个瓦片层，这在瓦片部分透明时是有意义的，例如来自OpenSeaMap的瓦片。

一些提供商提供几种变体的瓦片。它们通过在提供商名称后附加后缀来表示，由点分隔。例如：'OpenStreetMap'和'OpenStreetMap.BlackAndWhite'。

商业瓦片提供商期望某种类型的API密钥。这应该添加到选项中。通常，小型或非商业应用程序可以免费获得API密钥。

默认情况下，Locator支持几个瓦片提供商。它们各自在src/tiles目录中有一个PHP类文件。目前，支持以下瓦片提供商（未来可能还有更多）

如果未设置$tile，则Locator使用来自OpenStreetMap的瓦片。

地理编码名称

Locator的搜索功能使用来自geocoding service的信息。服务通过finder()方法的第一个参数设置。这可以是表示地理编码服务名称的string，或包含名称作为第一个元素以及选项的array。

通常情况下，除了一些提供者期望的API密钥外，不会有其他选项。其他选项可能会添加。

目前，定位器支持以下提供者（未来可能会有更多）

请注意，一些提供者可能规定您只能在相同提供者的地图瓦片上使用他们的服务。

如果您没有明确设置地理编码器，Leaflet-search将使用Nominatim。

标记类型

在属性$marker以及像marker()、modelMarker()等方法中，可以设置标记类型。这是一个包含[ 'type' => '<marker type>' ]的array，并补充了标记选项（取决于类型）。例如

$map->marker = [ 'type' => 'Marker', 'opacity' => 0.5 ]

除了Leaflet自带的Marker和CircleMarker外，Locator还提供两种其他标记

DotMarker

CircleMarker的简单扩展。它具有固定的半径，并且始终具有（至少）类名'dot-marker'。Locator的默认标记是一个DotMarker。

SpriteMarker

一个具有DivIcon的标记。使用此方法显示FontAwesome标记，如下所示

$map->marker = [ 'type' => 'SpriteMarker', 'html' => '<i class="far fa-2x fa-dog"></i>' ]

sjaakp / yii2-locator

维护者

详细信息