# 鸿蒙宝藏案例详解：共享单车“丝滑”骑行体验的代码实现 🚲💻
大家好！上次分享了鸿蒙那个超棒的共享单车体验案例，很多朋友留言说想看代码细节。没问题！这就带大家深入代码层，看看那些“丝滑”的体验（扫码直达、实时状态窗、路径规划）到底是怎么敲出来的。官方文档有时像藏宝图，代码才是真金白银！
> **核心目标再强调：** 用HarmonyOS的`Scan Kit`(扫码直达)、`Map Kit`(找车导航)、`Live View Kit`(实况窗)三大能力，把扫码->解锁->骑行->还车->支付的流程做到**极简、实时、无感**。
## 🎯 模块一：扫码直达解锁页 (Scan Kit)
**目标：** 用户在任何地方扫码，直接跳转到该单车的解锁确认页，跳过打开App、找入口的步骤。
### 关键代码详解 (TypeScript/ArkTS)
```
// 1. 导入关键模块
import scanBarcode from '@ohos.abilityAccessCtrl'; // Scan Kit核心模块
import { router } from '@kit.ArkUI'; // 页面路由模块
import { BusinessError } from '@kit.BasicServicesKit'; // 错误处理
// 2. 扫码工具类 (ScanUtil.ts)
export class ScanUtil {
public static scan(obj: Object): void {
// 3. 配置扫码选项：支持所有类型码(ALL)和一维码(ONE_D_CODE)，允许多码识别，允许从相册选图
let options: scanBarcode.ScanOptions = {
scanTypes: [scanBarcode.ScanType.ALL, scanBarcode.ScanType.ONE_D_CODE],
enableMultiMode: true,
enableAlbum: true
};
try {
// 4. 启动扫码并等待结果 (异步Promise)
scanBarcode.startScanForResult(getContext(obj), options)
.then((result: scanBarcode.ScanResult) => {
console.info('扫码结果:', JSON.stringify(result));
// 5. 关键逻辑：判断扫码类型 (假设CyclingConstants.SCAN_TYPE代表单车码)
if (result.scanType === CyclingConstants.SCAN_TYPE) {
// 6. 设置应用状态：等待解锁 (AppStorage是鸿蒙的状态管理)
AppStorage.setOrCreate(CyclingConstants.CYCLING_STATUS, CyclingStatus.WAITING_UNLOCK);
// 7. 核心跳转！直接路由到解锁确认页 'pages/ConfirmUnlock'
router.pushUrl({ url: 'pages/ConfirmUnlock' });
// 通常这里会把扫码得到的数据(如单车ID)通过params传递给ConfirmUnlock页面
}
})
.catch((error: BusinessError) => {
console.error('扫码出错:', JSON.stringify(error));
// 处理错误：如提示用户、重试等
});
} catch (error) {
console.error('启动扫码失败:', JSON.stringify(error));
}
}
}
```
**代码解析 & 关键点：**
1. **权限申请 (`module.json5`):** 扫码必须的相机权限！**必须在配置文件声明**：
```
"requestPermissions": [
{
"name": "ohos.permission.CAMERA",
"reason": "用于扫描共享单车二维码", // 给用户看的理由
"usedScene": {
"abilities": ["EntryAbility"], // 在哪个Ability申请
"when": "always" // 使用时机
}
}
],
```
1. **`ScanOptions` 配置灵活：**
- `scanTypes`: 指定识别的码类型，非常灵活。
- `enableMultiMode`: 是否一次扫多个码（共享单车通常不需要，关掉更快）。
- `enableAlbum`: 是否允许从相册选择二维码图片（重要！用户可能截图扫码）。
1. **`startScanForResult`:** 这是启动扫码的核心API，返回一个`Promise`。`.then()`里处理成功结果，`.catch()`处理失败。
1. **结果处理 (`result`):**
- `result.scanType`: 识别出的码类型（二维码？条形码？）。
- `result.value`: 扫码得到的数据字符串（通常包含单车唯一ID、解锁指令等）。**这个例子简化了，实际业务中这里会解析`result.value`获取单车信息！**
1. **状态管理 (`AppStorage`):** 鸿蒙提供的应用级状态管理。这里设置`CYCLING_STATUS = WAITING_UNLOCK`，告诉应用“用户扫到码了，等待确认解锁”。这个状态会被解锁页面使用。
1. **`router.pushUrl`:** **实现“直达”的关键！** 直接路由导航到解锁确认页`pages/ConfirmUnlock`。用户瞬间从扫码界面跳到了解锁按钮面前，省去所有中间步骤。通常会把单车ID等信息通过`params`传递过去：`router.pushUrl({ url: 'pages/ConfirmUnlock', params: { bikeId: parsedBikeId } })`。
**调用时机：** 在你的首页(`Index`)、共享单车功能页(`BikePage`)，甚至一个桌面万能卡片(`Card`)的按钮点击事件里，调用`ScanUtil.scan(this)`即可触发扫码。
* * *
## 🗺️ 模块二：智能找车与步行导航 (Map Kit)
**目标：** 在“找车”页面，显示用户位置、车辆位置，并绘制步行路线。
### 关键代码详解 (地图初始化、定位、路径规划与绘制)
```
// 1. 导入关键模块
import { MapComponent, mapCommon, map, navi } from '@kit.MapKit'; // 地图核心
import geoLocationManager from '@ohos.geoLocationManager'; // 定位管理
import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; // 权限申请
import { BusinessError } from '@kit.BasicServicesKit';
// 2. 在找车页面 (FindBikePage.ets)
@Entry
@Component
struct FindBikePage {
// ... 其他状态变量 ...
private mapController?: map.MapComponentController; // 地图控制器
private mapPolyline?: map.MapPolyline; // 用于绘制路线的线对象
private myPosition: mapCommon.LatLng = { latitude: 0, longitude: 0 }; // 用户位置
aboutToAppear(): void {
// 3. 初始化地图回调
this.callback = async (err, mapController) => {
if (!err) {
this.mapController = mapController;
this.mapController.on('mapLoad', async () => {
// 4. 检查并申请定位权限
const hasPerm = await this.checkLocationPermissions();
if (hasPerm) {
this.enableMyLocation(); // 开启定位并获取位置
}
});
}
};
}
// 5. 检查定位权限
private async checkLocationPermissions(): Promise<boolean> {
const atManager = abilityAccessCtrl.createAtManager();
try {
const permissions = [
'ohos.permission.LOCATION',
'ohos.permission.APPROXIMATELY_LOCATION'
];
const grantStatus = await atManager.checkAccessToken(
abilityAccessCtrl.AccessTokenID.BASE,
permissions
);
return grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
} catch (error) {
console.error('检查权限出错', error);
return false;
}
}
// 6. 申请定位权限
private requestPermissions(): void {
const atManager = abilityAccessCtrl.createAtManager();
atManager.requestPermissionsFromUser(
getContext(this) as common.UIAbilityContext,
['ohos.permission.LOCATION', 'ohos.permission.APPROXIMATELY_LOCATION']
).then(() => {
this.enableMyLocation(); // 权限获取成功，开启定位
}).catch((err: BusinessError) => {
console.error('申请权限失败', err.code, err.message);
});
}
// 7. 开启定位并获取当前位置
private enableMyLocation(): void {
if (!this.mapController) return;
// 7.1 设置地图显示我的位置
this.mapController.setMyLocationEnabled(true);
this.mapController.setMyLocationControlsEnabled(true); // 显示定位按钮
// 7.2 配置定位请求参数 (高精度、首次定位)
let requestInfo: geoLocationManager.CurrentLocationRequest = {
priority: geoLocationManager.LocationRequestPriority.FIRST_FIX,
scenario: geoLocationManager.LocationRequestScenario.NAVIGATION,
maxAccuracy: 50 // 精度要求(米)
};
// 7.3 获取当前位置
geoLocationManager.getCurrentLocation(requestInfo)
.then(async (location) => {
console.info('获取到位置:', location.latitude, location.longitude);
// 7.4 坐标转换 (WGS84 -> 国内常用的GCJ02)
let mapPosition: mapCommon.LatLng = await map.convertCoordinate(
mapCommon.CoordinateType.WGS84,
mapCommon.CoordinateType.GCJ02,
{ latitude: location.latitude, longitude: location.longitude }
);
// 7.5 存储用户位置 & 移动地图视角
this.myPosition = mapPosition;
AppStorage.setOrCreate('userLat', mapPosition.latitude);
AppStorage.setOrCreate('userLon', mapPosition.longitude);
let cameraUpdate = map.newCameraPosition({
target: mapPosition,
zoom: 16 // 放大到合适级别
});
this.mapController?.animateCamera(cameraUpdate, 1000); // 1秒动画移动到用户位置
})
.catch((err: BusinessError) => {
console.error('获取位置失败', err.code, err.message);
});
}
// 8. 监听地图点击 (用户点选单车位置)
private setupMapListeners(): void {
this.mapController?.on('mapClick', async (clickedPosition: mapCommon.LatLng) => {
// 8.1 清除旧标记和路线
this.mapController?.clear();
this.mapPolyline?.remove();
// 8.2 在点击位置添加一个标记 (Marker)
this.marker = await MapUtil.addMarker(clickedPosition, this.mapController);
// 8.3 关键！发起步行路径规划 (从用户位置this.myPosition 到 点击位置clickedPosition)
const walkingRoutes = await MapUtil.walkingRoutes(clickedPosition, this.myPosition);
if (walkingRoutes && walkingRoutes.routes.length > 0) {
// 8.4 绘制规划好的步行路线
await MapUtil.paintRoute(walkingRoutes, this.mapPolyline, this.mapController);
}
});
}
build() {
Column() {
// 9. 集成地图组件 (核心UI)
MapComponent({
mapOptions: { ... }, // 地图初始配置 (中心点、缩放级别等)
mapCallback: this.callback // 地图加载完成的回调
})
.onClick(() => {
this.setupMapListeners(); // 通常在地图加载后设置监听
})
.width('100%')
.height('100%')
}
}
}
// 10. 路径规划工具类 (MapUtil.ts)
export class MapUtil {
// 10.1 步行路径规划
public static async walkingRoutes(
destination: mapCommon.LatLng,
origin?: mapCommon.LatLng
): Promise<navi.RouteResult | undefined> {
if (!origin) return undefined;
let params: navi.RouteParams = {
origins: [origin], // 起点数组 (这里一个)
destination: destination, // 终点
type: navi.RouteType.WALKING, // 步行模式
language: 'zh_CN' // 中文结果
};
try {
const result = await navi.getWalkingRoutes(params); // 调用Map Kit API
console.info('步行路线规划成功', JSON.stringify(result));
return result;
} catch (err) {
console.error('步行路线规划失败', JSON.stringify(err));
return undefined;
}
}
// 10.2 绘制路线到地图
public static async paintRoute(
routeResult: navi.RouteResult,
mapPolyline: map.MapPolyline | undefined,
mapController?: map.MapComponentController
) {
if (!mapController || !routeResult.routes[0]?.overviewPolyline) return;
// 清除旧线
mapPolyline?.remove();
// 配置新线的样式 (蓝色，20像素宽)
let polylineOption: mapCommon.MapPolylineOptions = {
points: routeResult.routes[0].overviewPolyline, // 路线坐标点数组
clickable: true,
width: 20,
color: 0xFF2970FF, // ARGB 蓝色
zIndex: 10
};
// 添加折线到地图并保存引用
mapPolyline = await mapController.addPolyline(polylineOption);
return mapPolyline;
}
// ... (addMarker 方法类似) ...
}
```
**代码解析 & 关键点：**
1. **权限 (`module.json5`):** 定位权限同样**必须声明**：
```
"requestPermissions": [
{
"name": "ohos.permission.LOCATION",
"reason": "用于查找附近的共享单车和导航"
},
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "用于更精准的找车定位"
}
],
```
1. **`MapComponent`:** 地图的UI组件。`mapCallback` 在地图**加载完成**后触发，此时才能安全地获取`mapController`进行操作。
1. **定位流程 (`enableMyLocation`):**
- `setMyLocationEnabled(true)`: 让地图显示用户位置蓝点。
- `getCurrentLocation`: 获取**一次**精确位置。对于持续追踪，需用`on('locationChange')`监听。
- **坐标转换 (`convertCoordinate`)：** **非常重要！** 设备GPS返回的是WGS84坐标，国内地图服务(如GCJ02)需要转换才能准确显示。
1. **路径规划 (`getWalkingRoutes`):**
- 调用 `navi.getWalkingRoutes(params)` 是核心。传入起点(`origins`)、终点(`destination`)、类型(`WALKING`)。
- 返回的 `RouteResult` 包含路线信息，其中 `overviewPolyline` 是**一串压缩过的经纬度点**，用于绘制路线。
1. **绘制路线 (`addPolyline`):**
- 使用 `mapController.addPolyline(options)` 绘制折线。
- `options.points` 传入路线规划得到的坐标点数组 (`overviewPolyline` 需要先解码，示例代码假设`MapUtil.walkingRoutes`内部或返回结果已处理)。
- 通过 `width`, `color` 等属性定制路线外观。
1. **交互流程：** 用户点击地图 -> 获取点击点坐标 -> 清除旧数据 -> 添加新Marker -> 规划并绘制到该Marker的步行路线。
* * *
## ✨ 模块三：实况窗展示骑行状态 (Live View Kit)
**目标：** 解锁后，在状态栏(胶囊)、通知中心、锁屏实时显示骑行状态/时长/费用；还车后变待支付；支付后结束。
### 关键代码详解 (创建、更新、销毁实况窗)
```
// 1. 导入关键模块
import liveViewManager, { LiveViewDataBuilder, TextLayoutBuilder, TextCapsuleBuilder, LiveNotification, LiveViewContext } from '@kit.LiveViewKit';
import { BusinessError } from '@kit.BasicServicesKit';
import wantAgent from '@ohos.app.ability.wantAgent'; // 用于定义点击动作
// 2. 实况窗控制类 (LiveViewController.ts)
export class LiveViewController {
private liveViewData?: liveViewManager.LiveViewData; // 当前实况窗数据
private liveNotification?: LiveNotification; // 实况窗通知对象
// 3. 创建并显示实况窗 (在用户点击"解锁"后调用)
public async startLiveView(context: LiveViewContext): Promise<liveViewManager.LiveViewResult> {
// 3.1 构建默认的实况窗数据 (骑行中状态)
this.liveViewData = await this.buildDefaultView(context);
// 3.2 创建LiveNotification对象 (关联环境信息，如业务类型'RENT')
let env: liveViewManager.LiveViewEnvironment = { id: 0, event: 'RENT' };
this.liveNotification = LiveNotification.from(context, env);
// 3.3 创建并显示实况窗！
return await this.liveNotification.create(this.liveViewData);
}
// 4. 构建默认骑行中状态的实况窗数据
private static async buildDefaultView(context: LiveViewContext): Promise<liveViewManager.LiveViewData> {
// 4.1 构建展开态卡片布局 (锁屏/通知中心看到的卡片)
const layoutData = new TextLayoutBuilder()
.setTitle('骑行中') // 卡片标题
.setContent('已骑行 0 分钟') // 卡片内容 (初始0分钟)
.setDescPic('bike_icon.png'); // 卡片右侧图标
// 4.2 构建胶囊态 (状态栏看到的小胶囊)
const capsule = new TextCapsuleBuilder()
.setIcon('bike_small.png') // 胶囊图标
.setBackgroundColor('#FF00FF00') // 胶囊背景色 (绿色)
.setTitle('骑行中'); // 胶囊文字
// 4.3 构建点击动作 (点击实况窗跳转回App的骑行页面)
const wantAgentInfo: wantAgent.WantAgentInfo = {
wants: [
{
bundleName: context.bundleName,
abilityName: 'EntryAbility',
parameters: { route: 'pages/RidingPage' } // 跳转到骑行页
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0
};
const wantAgentObj = await wantAgent.getWantAgent(wantAgentInfo);
// 4.4 构建完整的LiveViewData
const liveViewData = new LiveViewDataBuilder()
.setTitle('骑行中') // 主标题
.setContentText(['已骑行 0 分钟']) // 内容文本数组 (可多行)
.setContentColor('#FFFFFFFF') // 内容文字颜色 (白色)
.setLayoutData(layoutData) // 设置卡片布局
.setCapsule(capsule) // 设置胶囊样式
.setWant(wantAgentObj) // 设置点击动作
// (可选) 配置锁屏沉浸态扩展Ability (见后面)
.setLiveViewLockScreenAbilityName('LiveViewLockScreenExtAbility')
.setLiveViewLockScreenPicture('bike_lock_icon.png')
.build(); // 构建完成
return liveViewData;
}
// 5. 更新实况窗状态 (骑行中 -> 待支付 -> 支付完成)
public async updateLiveView(status: number, context: LiveViewContext): Promise<liveViewManager.LiveViewResult> {
if (!this.liveViewData || !this.liveNotification) {
console.error('实况窗未创建或数据为空');
return { code: -1 };
}
switch (status) {
case CyclingStatus.RIDING: // 骑行中 (更新计时)
// ... 更新 this.liveViewData 的计时文本 (e.g., '已骑行 5 分钟') ...
return await this.liveNotification.update(this.liveViewData);
case CyclingStatus.WAITING_PAYMENT: // 还车成功，待支付
// 5.1 更新标题、内容、胶囊文字
this.liveViewData.primary.title = '待支付';
this.liveViewData.primary.content = [{ text: '骑行结束，点击支付', textColor: '#FFFFFFFF' }];
this.liveViewData.capsule.title = '待支付';
// 5.2 更新点击动作 (点击跳转到支付页)
this.liveViewData.primary.clickAction = await this.buildWantAgent(context, 'pages/PaymentPage');
// 5.3 更新卡片布局
this.liveViewData.primary.layoutData = new TextLayoutBuilder()
.setTitle('待支付')
.setContent('费用：¥2.50')
.setDescPic('payment_icon.png');
return await this.liveNotification.update(this.liveViewData);
case CyclingStatus.PAYMENT_COMPLETED: // 支付完成
// 5.4 更新为最终状态
this.liveViewData.primary.title = '支付成功';
this.liveViewData.primary.content = [{ text: '行程已完成，感谢使用', textColor: '#FFFFFFFF' }];
this.liveViewData.capsule.title = '完成';
// 5.5 关键！停止实况窗 (显示最终状态几秒后消失)
return await this.liveNotification.stop(this.liveViewData);
default:
return { code: -1 };
}
}
// ... (buildWantAgent 辅助方法) ...
}
// 6. 锁屏沉浸态实况窗扩展Ability (LiveViewLockScreenExtAbility.ets)
import { LiveViewLockScreenExtensionAbility, UIExtensionContentSession } from '@kit.LiveViewKit';
import hilog from '@ohos.hilog';
export default class LiveViewLockScreenExtAbility extends LiveViewLockScreenExtensionAbility {
onSessionCreate(want: Want, session: UIExtensionContentSession) {
hilog.info(0x0000, 'LiveViewLock', '锁屏扩展Ability创建会话');
// 6.1 加载自定义的锁屏实况窗UI页面
session.loadContent('pages/LiveViewLockScreenPage'); // 这个页面你用ArkUI自己设计！
}
// ... (其他生命周期方法 onForeground, onBackground, onDestroy) ...
}
```
**代码解析 & 关键点：**
1. **`LiveViewDataBuilder`:** 构建实况窗数据的核心工具。它定义了：
- **主信息 (`primary`):** 标题、内容文本/颜色、点击动作(`WantAgent`)、卡片布局(`LayoutData`)、锁屏扩展能力名/参数/图片。
- **胶囊态 (`capsule`):** 状态栏显示的图标、背景色、文字。
- **其他:** 显示时长(`keepTime`)、是否持久化等。
1. **状态管理：** 实况窗内容不是静态的！`updateLiveView` 方法根据业务状态 (`RIDING`, `WAITING_PAYMENT`, `PAYMENT_COMPLETED`) **动态更新** `liveViewData` 的各个部分，然后调用 `update()` 或 `stop()` 刷新界面。
1. **`WantAgent`:** **实现点击交互的关键！** 定义了用户点击实况窗（胶囊或卡片）后要执行的动作。最常见的就是跳转回App的特定页面（如骑行页、支付页）。`wantAgent` 模块用于构建这个意图。
1. **`LiveNotification`:** 负责实况窗的生命周期管理 (`create`, `update`, `stop`)。`.from(context, env)` 将实况窗与特定的业务环境(`env`)关联起来。
1. **沉浸态锁屏实况窗 (高级):**
- 在 `LiveViewDataBuilder` 中配置 `setLiveViewLockScreenAbilityName` 和 `setLiveViewLockScreenPicture`。
- 实现一个继承自 `LiveViewLockScreenExtensionAbility` 的Ability。
- 在 `onSessionCreate` 方法中，使用 `session.loadContent('你的自定义UI页面路径')` 加载你用ArkUI编写的**自定义锁屏卡片界面**。这让你可以展示比默认模板更丰富的信息（比如地图缩略图、更详细的费用明细）。
- **声明扩展Ability (`module.json5`):**
```
"extensionAbilities": [
{
"name": "LiveViewLockScreenExtAbility",
"type": "liveViewLockScreen", // 类型必须为liveViewLockScreen
"srcEntry": "./ets/entryability/LiveViewLockScreenExtAbility.ets",
"exported": true // 允许系统访问
}
],
```
1. **服务开通：** 使用实况窗能力**前**，需要在 `AppGallery Connect` 后台为你的应用开通 `Live View Kit` 服务权益。
* * *
## 📌 总结与思考
把这三块核心代码串起来，就构成了那个“丝滑”骑行体验的骨架：
1. **`ScanUtil.scan()`** 被调用 -> 扫码成功 -> `router.pushUrl` 直达解锁页。
1. 用户点击解锁 -> 调用 **`LiveViewController.startLiveView()`** 创建实况窗 (显示骑行中)。
1. 骑行中
