时区选择器技术文档

2024-12-26 14:00:47作者：翟江哲Frasier

1. 安装指南

1.1 环境要求

在使用时区选择器之前，请确保您的系统满足以下要求：

jQuery：时区选择器依赖于jQuery库。
地图API：您需要选择使用Google Maps JavaScript API v3或OpenLayers作为地图渲染引擎。

1.2 安装步骤

下载时区数据文件：从项目中提供的tz_json.tgz文件中提取时区数据文件，并将其放置在服务器上可访问的位置。
引入依赖库：在您的HTML文件中引入jQuery和所选的地图API（Google Maps或OpenLayers）。
配置时区选择器：在您的JavaScript代码中配置时区选择器，并指定jsonRootUrl选项为时区数据文件的路径。

2. 项目的使用说明

2.1 基本使用

时区选择器可以通过以下步骤快速集成到您的网站中：

引入依赖：确保您的页面已经引入了jQuery和地图API。
初始化时区选择器：在您的JavaScript代码中初始化时区选择器，并配置相关选项。
运行示例：您可以通过运行项目中的示例文件gmaps_example.html或openlayers_example.html来查看时区选择器的实际效果。

2.2 示例代码

以下是一个简单的示例代码，展示如何在Google Maps中使用时区选择器：

<!DOCTYPE html>
<html>
<head>
  <title>时区选择器示例</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
  <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  <script src="path/to/timezone-picker.js"></script>
</head>
<body>
  <div id="map" style="height: 500px; width: 100%;"></div>
  <script>
    $(document).ready(function() {
      var map = new google.maps.Map(document.getElementById('map'), {
        center: {lat: 0, lng: 0},
        zoom: 2
      });

      var timezonePicker = new TimezonePicker({
        map: map,
        jsonRootUrl: '/path/to/tz_json/'
      });
    });
  </script>
</body>
</html>

3. 项目API使用文档

3.1 配置选项

时区选择器提供了多种配置选项，您可以根据需要进行调整：

fillColor：时区填充颜色，默认值为#ffcccc。
fillOpacity：时区填充透明度，默认值为0.5。
initialLat：地图初始中心点的纬度，默认值为0。
initialLng：地图初始中心点的经度，默认值为0。
initialZoom：地图初始缩放级别，范围为1-20，默认值为2。
jsonRootUrl：时区数据文件的根路径，默认值为/tz_json/。
strokeColor：时区轮廓颜色，默认值为#ff0000。
strokeWeight：时区轮廓宽度，默认值为2。
strokeOpacity：时区轮廓透明度，默认值为0.7。
onHover：鼠标悬停时区时的回调函数。
onReady：所有数据文件加载完成时的回调函数。
onSelected：选择时区时的回调函数。
useOpenLayers：是否使用OpenLayers代替Google Maps，默认值为false。

3.2 方法

时区选择器提供了以下方法供您调用：

showInfoWindow(htmlString)：显示当前选中区域的信息窗口，参数为HTML字符串。
hideInfoWindow()：隐藏信息窗口。
setDate(Date)：设置时区选择器的相对日期，以正确显示时区名称（如EST vs EDT）。
selectZone(olsonName)：以编程方式选择指定的时区。

3.3 CSS类

时区选择器使用以下CSS类进行样式控制：

timezone-picker-infowindow：信息窗口的主内容容器。

如果您使用Twitter Bootstrap和Google Maps或OpenLayers，可能需要添加以下CSS以防止地图控件失真：

#zonepicker img {
  max-width: none;
}

4. 项目安装方式

4.1 使用预生成的时区数据文件

如果您不打算生成自己的时区数据文件，可以直接使用项目中提供的tz_json.tgz文件。只需将该文件解压到服务器上可访问的位置，并在配置时区选择器时指定jsonRootUrl选项。

4.2 生成时区数据文件

如果您需要生成自己的时区数据文件，请按照以下步骤操作：

安装依赖：
- Python 2.6+
- libgeos-dev（在Ubuntu上使用sudo apt-get install libgeos-dev，在Mac OS上使用brew install geos）
- pip（使用sudo easy_install pip安装）
- shapely（使用sudo pip install shapely安装）
- pytz（使用sudo pip install pytz安装）
- simplejson（使用sudo pip install simplejson安装）
下载时区形状文件：
- 从http://efele.net/maps/tz/world/tz_world.zip下载并解压tz_world文件。
生成时区数据文件：
- 运行以下命令生成时区数据文件：
```
python script/gen_json.py <path-to-tz_world.shp> <output-dir>
```
- 请耐心等待，生成过程可能需要一些时间。