# Tmap.extend.js

**Repository Path**: chumbir/tmap.extend.js

## Basic Information

- **Project Name**: Tmap.extend.js
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tmap.extend.js

轻量的天地图定位 SDK。一套 JS 同时适配 **普通浏览器 / Vue / uni-app（H5 / web-view）**，参数与回调习惯对齐 `uni.getLocation`，但**不依赖、不调用** `uni.getLocation`。

- 独立实现，零第三方依赖
- 同时支持 Promise 和 `success / fail / complete` 回调
- 定位结果来源可辨（`provider: browser / ip / native`），默认不做静默回退

## 特性

| 能力 | 说明 |
| --- | --- |
| 浏览器定位 | 天地图 `T.Geolocation` |
| IP 定位 | 天地图 `T.LocalCity`，无需浏览器授权 |
| 逆地理编码 | `geocode: true` 时用 `T.Geocoder` 补 `address` |
| 显式回退 | 仅当 `fallback: true` 时才回退原生 `navigator.geolocation`，结果标 `provider: 'native'` |
| 脚本去重 | 天地图 JS API 按 URL 做 Promise 级去重缓存，可安全并发调用 |

## 仓库结构

```
TMAP-EXTEND-JS/
├── demo.html                  # 开箱即用的调用示例
└── tmap.extend.js/            # npm 包本体
    ├── index.mjs              # ESM 源码（唯一源码）
    ├── index.cjs              # CommonJS 入口
    ├── tmap.extend.js         # UMD 构建产物（浏览器 <script> 直引）
    ├── scripts/build-umd.cjs  # 构建脚本：index.mjs -> tmap.extend.js
    └── package.json
```

## 安装

```bash
npm i tmap.extend.js
```

或直接用 `<script>` 引入 `tmap.extend.js/tmap.extend.js`。

## 快速上手

### Vue / uni-app / Vite（ESM）

```js
import Tmap from 'tmap.extend.js'

const tmap = Tmap.extend.createLocation({
  tk: '你的天地图 tk',
})

// 浏览器定位：默认只走天地图，失败直接报错，不悄悄换数据源
try {
  const res = await tmap.getLocation({ geocode: true })
  console.log(res.latitude, res.longitude, res.address?.formattedAddress, res.provider)
} catch (err) {
  console.error(err.errMsg) // 例如 getLocation:fail 定位超时
}

// 需要兜底原生定位时，显式开启 fallback（结果 provider 为 'native'）
const res2 = await tmap.getLocation({ fallback: true })

// IP 定位（无需浏览器授权）
const city = await tmap.ipLocation()
console.log(city.cityName, city.lnglat)
```

### 浏览器 &lt;script&gt;

```html
<script src="./tmap.extend.js/tmap.extend.js"></script>
<script>
  Tmap.extend.getLocation({
    tk: '你的天地图 tk',
    success(res) { console.log(res.latitude, res.longitude, res.provider) },
    fail(err) { console.error(err.errMsg) },
  })
</script>
```

### CommonJS

```js
const Tmap = require('tmap.extend.js')
```

## API

### `Tmap.extend.getLocation(options)`

浏览器定位。**默认仅使用天地图 `T.Geolocation`**，任何失败（脚本加载失败、缺少 tk、未授权、超时等）都会直接 reject，错误带 `errMsg`（`方法名:fail 原因`）和 `provider: 'browser'`。只有显式传 `fallback: true`，才会在天地图失败时回退原生 `navigator.geolocation`，此时结果 `provider: 'native'`。

### `Tmap.extend.ipLocation(options)`

IP 定位，使用天地图 `T.LocalCity`，不需要浏览器授权。

### `Tmap.extend.createLocation(defaults)`

工厂方法，预设默认参数（如 `tk`），返回带 `getLocation / ipLocation / loadTiandituScript` 的实例。

### `Tmap.extend.loadTiandituScript(options)`

手动加载天地图 JS API，返回 `Promise<T>`。

## 参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `tk` | string | - | 天地图密钥，必填（可由 `createLocation` 预设） |
| `geocode` | boolean | `false` | 逆地理编码，补 `address` / `formattedAddress` |
| `timeout` | number | `10000` | 超时（毫秒） |
| `isHighAccuracy` / `enableHighAccuracy` | boolean | `false` | 是否高精度 |
| `highAccuracyExpireTime` | number | - | 高精度超时（兼容 uni 参数） |
| `maximumAge` | number | `0` | 缓存时间（毫秒）；或用 `cacheTimeout`（秒） |
| `fallback` | boolean | `false` | 浏览器定位失败时是否回退原生 geolocation |
| `apiUrl` | string | 天地图 v4.0 | JS API 地址 |
| `scriptId` | string | `tianditu-jsapi-v4` | script 标签 id |
| `windowRef` | object | `globalThis` | 全局引用（测试注入用） |
| `success` / `fail` / `complete` | function | - | uni 风格回调 |

## 返回值

```jsonc
{
  "latitude": 34.7466,
  "longitude": 113.6253,
  "lnglat": { "lat": 34.7466, "lng": 113.6253 },
  "cityName": "郑州市",
  "address": { "province": "河南省", "city": "郑州市" },
  "formattedAddress": "河南省郑州市...",
  "provider": "browser",
  "accuracy": 30,
  "raw": {}
}
```

`provider` 取值：

- `browser`：天地图浏览器定位（`T.Geolocation`）
- `ip`：天地图 IP 定位（`T.LocalCity`）
- `native`：`fallback: true` 回退到的原生定位（`navigator.geolocation`）

## 行为与注意事项

- **不做静默回退**：`getLocation` 失败会明确报错，绝不会悄悄换成原生定位的结果。错误对象带 `errMsg`、`method`、`provider`、`raw`。
- 浏览器定位需要 **HTTPS 或 localhost** 的安全上下文，并且需要用户授权。
- `geocode` 依赖天地图地理编码服务，逆地理失败不影响定位结果本身（只是没有 `address`）。
- 在 uni-app 中适用于 H5 与 web-view 场景。

## 本地 Demo

```bash
npx serve .
```

打开 `http://localhost:3000/demo.html`，填入天地图 `tk` 即可测试。支持 URL 参数直达：

```
demo.html?tk=你的tk&provider=browser&geocode=true
```

- `provider`：`browser` / `ip`；非安全上下文会自动切到 `ip`
- `geocode`：`true` / `false`
- 带上 `tk` 参数时页面会自动发起一次定位

## 构建

```bash
cd tmap.extend.js
npm run build    # index.mjs -> tmap.extend.js（UMD）
```

无任何 npm 依赖，Node 直接运行。

## 版本记录

- **0.2.0**（2026-09-08）：**行为变更**——移除 `getLocation` 默认静默回退原生定位；新增显式 `fallback` 选项，回退结果 `provider: 'native'`。依赖旧行为的调用方需显式加 `fallback: true`。
- **0.1.0**：首个发布版本。

## License

[MIT](./LICENSE)