快速开始 – tzf 项目

快速开始

Project tzf 提供多语言支持，可根据经纬度查询时区。

语言或服务	仓库	API 文档
Go	`ringsaturn/tzf`
Rust	`ringsaturn/tzf-rs`
Python	`ringsaturn/tzfpy`	`tzfpy.pyi`
Swift	`ringsaturn/tzf-swift`
Ruby	`HarlemSquirrel/tzf-rb`
JS (浏览器 Wasm)	`ringsaturn/tzf-wasm`
HTTP API	`racemap/rust-tz-service`
在线演示	`ringsaturn/tzf-web`

Go

go get github.com/ringsaturn/tzf

// 初始化大约使用 150MB 内存，GC 后约 60MB。
package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
)

func main() {
	finder, err := tzf.NewDefaultFinder()
	if err != nil {
		panic(err)
	}
	fmt.Println(finder.GetTimezoneName(116.6386, 40.0786))
}

如需 100% 准确的结果，请使用 NewFullFinder（尽可能复用实例——初始化开销较大）：

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
)

func main() {
	finder, err := tzf.NewFullFinder()
	if err != nil {
		panic(err)
	}
	fmt.Println(finder.GetTimezoneName(139.6917, 35.6895))
}

Rust

cargo add tzf-rs

use lazy_static::lazy_static;
use tzf_rs::DefaultFinder;

lazy_static! {
    static ref FINDER: DefaultFinder = DefaultFinder::new();
}

fn main() {
    // 坐标采用 (经度，纬度) 顺序。
    print!("{:?}\n", FINDER.get_tz_name(116.3883, 39.9289));
    print!("{:?}\n", FINDER.get_tz_names(116.3883, 39.9289));
}

完整精度支持（v1.3.0+）

自 v1.3.0 起，可通过可选的 Cargo feature 使用完整精度数据。由于完整数据集（约 17 MB）超出 crates.io 的大小限制，需要通过 git 依赖引用：

[dependencies]
tzf-rs = { git = "https://github.com/ringsaturn/tzf-rs", tag = "v{X}.{Y}.{Z}", features = ["full"], default-features = false }

use tzf_rs::DefaultFinder;

fn main() {
    let finder = DefaultFinder::new_full();
    let tz_name = finder.get_tz_name(139.767125, 35.681236);
    println!("tz_name: {}", tz_name);
}

Python

# 只安装 tzfpy
pip install tzfpy

# 安装 pytz 支持
pip install "tzfpy[pytz]"

# 安装 tzdata 支持
pip install "tzfpy[tzdata]"

# 通过 conda 安装
conda install -c conda-forge tzfpy

>>> from tzfpy import get_tz, get_tzs
>>> get_tz(116.3883, 39.9289)   # (经度，纬度) 顺序
'Asia/Shanghai'
>>> get_tzs(87.4160, 44.0400)   # 返回所有匹配的时区
['Asia/Shanghai', 'Asia/Urumqi']

Python 不支持完整精度模式。

Swift

将包添加到你的 Package.swift：

dependencies: [
    .package(url: "https://github.com/ringsaturn/tzf-swift.git", from: "{latest_version}")
]

import Foundation
import tzf

do {
    let finder = try DefaultFinder()

    let timezone = try finder.getTimezone(lng: 116.3833, lat: 39.9167)
    print("北京时区：", timezone)

    let timezones = try finder.getTimezones(lng: 87.5703, lat: 43.8146)
    print("可能存在的多个时区：", timezones)

    print("数据版本：", finder.dataVersion())
} catch {
    print("错误：", error)
}

Ruby

Ruby 支持由 HarlemSquirrel 创建和维护。详细文档请参见 tzf-rb。

bundle add tzf
# 或
gem install tzf

require 'tzf'

TZF.tz_name(40.74771675713742, -73.99350390136448)
# => "America/New_York"

TZF.tz_names(40.74771675713742, -73.99350390136448)
# => ["America/New_York"]

WebAssembly

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tzf-wasm 示例</title>
    <script type="module">
      import init, { WasmFinder } from "https://www.unpkg.com/tzf-wasm@v0.1.4/tzf_wasm.js";

      async function loadWasm() {
        await init();
        const finder = new WasmFinder();
        const timezone = finder.get_tz_name(-74.006, 40.7128);
        console.log("纽约时区：", timezone);
      }

      loadWasm();
    </script>
  </head>
  <body></body>
</html>

在线预览：http://ringsaturn.github.io/tzf-web/

CLI

Go 和 Rust 实现均提供了命令行工具。

Go CLI

go install github.com/ringsaturn/tzf/cmd/tzf@latest

tzf -lng 116.3883 -lat 39.9289

# 通过 stdin 批量处理
echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf -stdin-order lng-lat

Rust CLI

cargo install tzf-rs

tzf --lng 116.3883 --lat 39.9289

# 通过 stdin 批量处理
echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf --stdin-order lng-lat

NixOS 用户可以通过 Nix 安装 tzf-rs—— 详见 NixOS packages。

最后更新于 April 29, 2026