# dmap

**Repository Path**: didiopensource/dmap

## Basic Information

- **Project Name**: dmap
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dmap · 滴滴地图 Android SDK 开发资源

> 滴图出行技术开放平台（DiMap）Android SDK 的**开发者资源仓库**。汇集帮助你更快、更规范地集成滴滴地图 Android SDK 的各类资源——当前提供 **AI Agent 技能包 & 参考文档**,示例 Demo 正在路上。

<p>
  <img alt="platform" src="https://img.shields.io/badge/platform-Android-3DDC84">
  <img alt="minSdk" src="https://img.shields.io/badge/minSdk-24%20(Android%207.0)-orange">
  <img alt="language" src="https://img.shields.io/badge/lang-Java%20%2F%20Kotlin-blue">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-green">
</p>

滴滴地图 Android SDK 覆盖 **地图（Map）**、**定位（Location）**、**WebService**、**导航（Navigation）** 四大模块。本仓库不是 SDK 本身,而是围绕它的开发辅助资源集合,帮助你少踩坑、快接入。

---

## 仓库内容

| 内容 | 目录 | 状态 | 说明 |
|------|------|:----:|------|
| 🤖 AI 技能包 & 参考文档 | [`dmap-android-skills/`](dmap-android-skills/) | ✅ 可用 | 供 AI 编程助手加载的 Agent Skill,内含 49 篇分模块 API 参考文档,亦可直接阅读 |
| 📱 示例 Demo | `demo/`（规划中） | 🚧 即将推出 | 可运行的四大模块集成示例工程 |

> 📌 Roadmap:后续将新增各模块的**可运行示例代码(Demo App)**,与技能包中的参考文档相互印证。欢迎关注更新。

---

## 一、AI 技能包（`dmap-android-skills/`）

一个遵循 [Agent Skills](https://code.claude.com/docs/en/skills) 开放标准的技能包,让 AI 编程助手(如 Claude Code、Cursor、Codex 等)在**编写、审查、调试**滴滴地图 SDK 相关代码时,自动加载权威的 API 用法与示例,从而:

- ✅ 生成**符合官方规范**的代码,覆盖鉴权、隐私合规、生命周期管理等易错点
- ✅ 减少「幻觉」,不凭空捏造不存在的 API
- ✅ **渐进式加载**——按需检索对应模块文档,只在相关任务出现时占用上下文,空闲时几乎零开销

技能包本身也是一份**可直接阅读的开发手册**:`references/` 下每篇文档都包含包名与 import 路径、功能说明、完整代码示例、API 参数表与注意事项。

### 覆盖模块

| 模块 | 目录 | 核心能力 | 主要入口类 | 文档数 |
|------|------|---------|-----------|:---:|
| 🗺️ 地图 Map | `references/map/` | 地图视图与生命周期、标记/折线/多边形/圆形/热力图覆盖物、相机控制、事件、UI 设置 | `MapView` · `DiMap` | 25 |
| 📍 定位 Location | `references/location/` | 单次 / 连续 / 导航模式定位、结果与错误处理、监听回调 | `DMapLocationClient` | 7 |
| 🌐 WebService | `references/webservice/` | POI 搜索与输入提示、正逆地理编码、驾车/步行/骑行/公交路线规划 | `MapServiceClient` | 11 |
| 🧭 导航 Navigation | `references/navigation/` | 组件导航(一行接入)与自定义导航(UI 定制、诱导信息、TTS、主辅路切换) | `DMapNaviPage` · `DMapNavi` | 6 |

完整索引见 [`dmap-android-skills/SKILL.md`](dmap-android-skills/SKILL.md)。

### 安装与使用

**作为 Claude Code 技能**——复制到 skills 目录即可被自动发现:

```bash
# 项目级(仅当前项目可用)
mkdir -p .claude/skills && cp -r dmap-android-skills .claude/skills/

# 或用户级(所有项目可用)
cp -r dmap-android-skills ~/.claude/skills/
```

之后在对话中提出滴滴地图相关需求(如「用 DiMap 在地图上加一个标记」「集成滴滴导航」),助手会自动加载对应模块文档并给出规范代码。技能核心为 `SKILL.md` + `references/`,同样适用于其他兼容 Agent Skills 的工具。

> 🔒 安全提示:仅使用来自可信来源的技能。技能会赋予 AI 新能力,请在采用前审阅其内容。

**作为开发参考文档**——无需任何工具,直接阅读 `dmap-android-skills/references/<模块>/` 下的 Markdown 即可。

---

## 二、示例 Demo（即将推出）

规划中的 `demo/` 将提供覆盖四大模块的**可运行示例工程**,包含地图展示与覆盖物、定位、POI 搜索/路线规划、组件与自定义导航等端到端用法,与技能包中的参考文档配套。敬请期待。

---

## SDK 快速开始

> 以下为各模块最小可用示例,帮助建立整体印象;完整说明请查阅技能包对应参考文档。

**0. 全局初始化(隐私合规 + 鉴权,必做)** — 在 `Application.onCreate()` 中、调用任何 SDK 接口之前完成:

```java
public class DemoApp extends Application {
    @Override public void onCreate() {
        super.onCreate();
        // 1. 隐私合规授权(地图模块示例;定位/导航需分别调用对应 Privacy 类)
        DMapMapViewClientPrivacy.updatePrivacyShow(this, true, true);
        DMapMapViewClientPrivacy.updatePrivacyAgree(this, true);
        // 2. 鉴权初始化(Key 从官网控制台申请)
        DiDiAuth.init(this, "申请的Key");
    }
}
```

**1. 显示地图**

```xml
<com.dmap.api.maps.MapView
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
```

```java
MapView mapView = findViewById(R.id.map);
mapView.getMap(diMap -> { /* 地图就绪,可添加覆盖物、控制相机等 */ });
// 需在 Activity/Fragment 生命周期中转发 onStart/onResume/onPause/onStop/onDestroy
```

**2. 定位一次**

```java
DMapLocationClient client = new DMapLocationClient(context);
client.setLocationListener(location -> {
    if (location.getErrorCode() == DMapLocation.ErrorCode.SUCCESS) {
        double lat = location.getLatitude(), lng = location.getLongitude();
    }
});
DMapLocationClientOption option = new DMapLocationClientOption();
option.setOnceLocation(true);      // 单次定位
client.setLocationOption(option);
client.startLocation();
```

**3. 一行代码启动导航**

```java
Poi start = new Poi("起点名称", new LatLng(40.04809, 116.28115), "起点POI_ID");
Poi end   = new Poi("终点名称", new LatLng(39.89591, 116.32130), "终点POI_ID");
DMapNaviParams params = new DMapNaviParams(start, null, end);
params.setRouteStrategy(PathPlanningStrategy.DRIVING_DEFAULT);
params.setUseInnerVoice(true);     // 使用 SDK 内置 TTS 播报
DMapNaviPage.getInstance().showRouteActivity(context, params, callback);
```

---

## 环境要求

| 配置项 | 要求 |
|--------|------|
| Android SDK（minSdk） | API 24（Android 7.0） |
| CPU 架构 | `armeabi-v7a`、`arm64-v8a` |
| 语言 | Java / Kotlin |
| 导航模块额外要求 | targetSdk 26+、compileSdk 30、Kotlin 1.3.72、NDK 21 |

> Android 6.0+ 需运行时**动态申请位置权限**;Android 10+ 如需后台定位还需 `ACCESS_BACKGROUND_LOCATION`。各模块所需权限、三方依赖与混淆规则详见对应 `*-setup.md`。

## 接入前置

1. **申请 Key**:登录 [官网控制台 → 创建 Key](https://lbs.xiaojukeji.com/console/fe/managekey),提交应用**包名**与签名 **SHA1**。
2. **获取 SHA1**:`./gradlew :app:signingReport`,或 `keytool -list -v -keystore debug.keystore`(调试默认密码 `android`)。
3. ⚠️ `build.gradle` 的 `applicationId` 必须与 `AndroidManifest.xml` 的 `package` 一致,否则会导致 `INVALID_USER_SCODE`。
4. **下载 SDK**:[地图 SDK AAR 下载](https://lbs.didistatic.com/dimap-web-opensdk-public/openmap-doc/android-mapsdk-v1.0.477.aar),将 `.aar` 放入 `libs/` 并在 `build.gradle` 中引入。

---

## 相关资源

- 🏠 官网:[滴图出行技术开放平台](https://lbs.xiaojukeji.com)
- 🔑 控制台:[Key 管理](https://lbs.xiaojukeji.com/console/fe/managekey)
- 📖 技能清单与完整索引:[`dmap-android-skills/SKILL.md`](dmap-android-skills/SKILL.md)
- 🧩 Agent Skills 规范:[Claude Code · Skills 文档](https://code.claude.com/docs/en/skills)

## License

[MIT](https://opensource.org/licenses/MIT)