1. 导入依赖

import { FavoriteManager, FavoritePoiInfo } from "@bdmap/map";
import { LatLng } from "@bdmap/base";

2. 初始化管理器

export struct MyComponent {
    private favoriteMgr: FavoriteManager | null = null;

    aboutToAppear(): void {
        // 获取FavoriteManager单例实例
        this.favoriteMgr = FavoriteManager.getInstance();
    }

    aboutToDisappear(): void {
        // 销毁管理器，释放资源
        this.favoriteMgr?.destroy();
    }
}

3. 添加第一个收藏点

addFavorite(): void {
    if (this.favoriteMgr === null) {
        return;
    }

    const poiInfo: FavoritePoiInfo = {
        id: "",                    // 新增时传入空字符串，成功后自动回填
        poiName: "我的家",         // 收藏点名称（必填）
        pt: new LatLng(39.915, 116.404),  // 坐标（必填）
        timeStamp: 0              // 新增时传入0，成功后自动回填
    };

    const result: number = this.favoriteMgr.add(poiInfo);
    if (result === 1) {
        console.log(`添加成功！ID: ${poiInfo.id}`);
    }
}

FavoritePoiInfo

收藏点信息的数据结构：

interface FavoritePoiInfo {
    id: string;        // 收藏点唯一标识符，由底层自动生成
    poiName: string;   // 收藏点名称（必填，不能为空）
    pt: LatLng;        // 收藏点坐标（必填）
    timeStamp: number; // 收藏时间戳（毫秒），由底层自动生成
}

字段说明

LatLng 坐标范围

• 纬度（lat）：-90 到 90
• 经度（lng）：-180 到 180

1. getInstance() - 获取管理器实例

获取FavoriteManager单例实例。如果实例不存在，会自动创建并初始化。

方法签名：

public static getInstance(): FavoriteManager

返回值：

FavoriteManager: 管理器实例

使用示例：

const favoriteMgr: FavoriteManager = FavoriteManager.getInstance();

注意事项：

• 采用单例模式，整个应用生命周期内只有一个实例
• 首次调用时会自动初始化
• 不要使用new关键字创建实例

2. add() - 添加收藏点

添加一个新的收藏点到收藏夹中。

方法签名：

public add(poiInfo: FavoritePoiInfo): number

参数：

poiInfo: 收藏点信息对象

返回值：

• 1: 添加成功
• -1: 添加失败（名称为空或名称重复）
• -2: 添加失败（收藏点数量已满）
• 0: 添加失败（坐标无效或其他错误）

使用示例：

const poiInfo: FavoritePoiInfo = {
    id: "",
    poiName: "我的家",
    pt: new LatLng(39.915, 116.404),
    timeStamp: 0
};

const result: number = this.favoriteMgr.add(poiInfo);
if (result === 1) {
    // 添加成功，poiInfo.id 和 poiInfo.timeStamp 已自动回填
    console.log(`添加成功！ID: ${poiInfo.id}, 时间戳: ${poiInfo.timeStamp}`);
} else if (result === -1) {
    console.log("添加失败：名称为空或重复");
} else if (result === -2) {
    console.log("添加失败：收藏点已满");
} else {
    console.log("添加失败：坐标无效");
}

重要说明：

• 添加成功后，poiInfo.id和poiInfo.timeStamp会被自动回填
• 名称不能为空，且不能与已有收藏点名称重复
• 坐标必须在有效范围内
• 如果收藏点数量达到上限，会返回-2

3. getFavPoi() - 根据ID获取收藏点

根据收藏点ID查询单个收藏点的详细信息。

方法签名：

public getFavPoi(id: string): FavoritePoiInfo | null

参数：

id: 收藏点唯一标识符

返回值：

• FavoritePoiInfo: 收藏点信息，存在时返回
• null: 不存在或ID为空时返回

使用示例：

const poiId: string = "我的家_1704067200000";
const poiInfo: FavoritePoiInfo | null = this.favoriteMgr.getFavPoi(poiId);
if (poiInfo !== null) {
    console.log(`名称: ${poiInfo.poiName}`);
    console.log(`坐标: ${poiInfo.pt.lat}, ${poiInfo.pt.lng}`);
    console.log(`收藏时间: ${new Date(poiInfo.timeStamp).toLocaleString()}`);
} else {
    console.log("收藏点不存在");
}

注意事项：

• ID为空字符串时返回null
• 不存在的ID也会返回null
• 建议在使用前进行null检查

4. getAllFavPois() - 获取所有收藏点

获取收藏夹中所有的收藏点列表。

方法签名：

public getAllFavPois(): Array<FavoritePoiInfo> | null

返回值：

• Array<FavoritePoiInfo>: 收藏点数组，存在收藏点时返回
• null: 没有收藏点时返回

使用示例：

const allPois: Array<FavoritePoiInfo> | null = this.favoriteMgr.getAllFavPois();
if (allPois !== null && allPois.length > 0) {
    allPois.forEach((poi: FavoritePoiInfo) => {
        console.log(`ID: ${poi.id}`);
        console.log(`名称: ${poi.poiName}`);
        console.log(`坐标: ${poi.pt.lat}, ${poi.pt.lng}`);
    });
} else {
    console.log("暂无收藏点");
}

注意事项：

• 没有收藏点时返回null，不是空数组
• 使用前必须进行null检查
• 返回的数组按添加顺序排列

5. deleteFavPoi() - 删除收藏点

根据ID删除指定的收藏点。

方法签名：

public deleteFavPoi(id: string): boolean

参数：

id: 要删除的收藏点ID

返回值：

• true: 删除成功
• false: 删除失败（ID为空或收藏点不存在）

使用示例：

const poiId: string = "我的家_1704067200000";
const success: boolean = this.favoriteMgr.deleteFavPoi(poiId);
if (success) {
    console.log("删除成功");
    // 更新UI，移除对应的标记点等
} else {
    console.log("删除失败：收藏点不存在");
}

注意事项：

• ID为空字符串时返回false
• 删除不存在的收藏点也会返回false
• 删除操作不可恢复，建议添加确认提示

6. clearAllFavPois() - 清空所有收藏点

清空收藏夹中的所有收藏点。

方法签名：

public clearAllFavPois(): boolean

返回值：

• true: 清空成功
• false: 清空失败

使用示例：

const success: boolean = this.favoriteMgr.clearAllFavPois();
if (success) {
    console.log("已清空所有收藏点");
    // 清除地图上的所有标记点
    this.mapController?.removeOverlays();
} else {
    console.log("清空失败");
}

注意事项：

• 此操作不可恢复，建议添加二次确认
• 清空后需要同步更新UI，移除地图上的标记点
• 即使没有收藏点，调用此方法也会返回true

7. updateFavPoi() - 更新收藏点

更新指定ID的收藏点信息。

方法签名：

public updateFavPoi(id: string, info: FavoritePoiInfo): boolean

参数：

• id: 要更新的收藏点ID
• info: 新的收藏点信息

返回值：

• true: 更新成功
• false: 更新失败（ID为空、名称无效或坐标无效）

使用示例：

const poiId: string = "我的家_1704067200000";
const updatedInfo: FavoritePoiInfo = {
    id: poiId,
    poiName: "更新后的名称",
    pt: new LatLng(39.920, 116.410),  // 新的坐标
    timeStamp: Date.now()
};

const success: boolean = this.favoriteMgr.updateFavPoi(poiId, updatedInfo);
if (success) {
    console.log("更新成功");
    // 更新地图上的标记点位置
} else {
    console.log("更新失败");
}

注意事项：

• 更新时名称不能为空
• 坐标必须在有效范围内
• ID必须与要更新的收藏点ID一致
• 更新成功后，建议同步更新地图上的标记点

8. destroy() - 销毁管理器

销毁管理器实例，释放资源。建议在组件销毁时调用。

方法签名：

public destroy(): void

使用示例：

aboutToDisappear(): void {
    this.favoriteMgr?.destroy();
}

注意事项：

• 调用destroy()后，单例实例会被置为null
• 下次调用getInstance()时会重新创建实例
• 建议在组件或页面的aboutToDisappear()生命周期中调用
• 销毁后，已保存的收藏点数据不会丢失，重新获取实例后仍可访问

以下是最简化的实现示例，展示如何用最少的代码实现所有核心功能：

import { FavoriteManager, FavoritePoiInfo } from "@bdmap/map_walkride_search";
import { LatLng } from "@bdmap/map_walkride_search";

@ComponentV2
export struct MinimalFavoriteDemo {
    private favoriteMgr: FavoriteManager | null = null;

    aboutToAppear(): void {
        // 步骤1：获取管理器实例
        this.favoriteMgr = FavoriteManager.getInstance();
    }

    aboutToDisappear(): void {
        // 步骤8：销毁管理器
        this.favoriteMgr?.destroy();
    }

    // 步骤2：添加收藏点
    add(): void {
        const poi: FavoritePoiInfo = {
            id: "",
            poiName: "我的家",
            pt: new LatLng(39.915, 116.404),
            timeStamp: 0
        };
        const result: number = this.favoriteMgr?.add(poi) || 0;
        if (result === 1) {
            console.log(`成功，ID: ${poi.id}`);
        }
    }

    // 步骤3：获取所有收藏点
    getAll(): void {
        const all: Array<FavoritePoiInfo> | null = this.favoriteMgr?.getAllFavPois() || null;
        if (all !== null) {
            all.forEach((poi: FavoritePoiInfo) => {
                console.log(`${poi.poiName}: ${poi.pt.lat}, ${poi.pt.lng}`);
            });
        }
    }

    // 步骤4：根据ID获取收藏点
    getById(id: string): void {
        const poi: FavoritePoiInfo | null = this.favoriteMgr?.getFavPoi(id) || null;
        if (poi !== null) {
            console.log(poi.poiName);
        }
    }

    // 步骤5：更新收藏点
    update(id: string): void {
        const info: FavoritePoiInfo = {
            id: id,
            poiName: "新名称",
            pt: new LatLng(39.920, 116.410),
            timeStamp: Date.now()
        };
        this.favoriteMgr?.updateFavPoi(id, info);
    }

    // 步骤6：删除收藏点
    delete(id: string): void {
        this.favoriteMgr?.deleteFavPoi(id);
    }

    // 步骤7：清空所有收藏点
    clear(): void {
        this.favoriteMgr?.clearAllFavPois();
    }

    build() {
        Column() {
            Button("添加").onClick(() => this.add())
            Button("查询全部").onClick(() => this.getAll())
            Button("查询单个").onClick(() => this.getById("id_here"))
            Button("更新").onClick(() => this.update("id_here"))
            Button("删除").onClick(() => this.delete("id_here"))
            Button("清空").onClick(() => this.clear())
        }
    }
}

Q1: 为什么添加收藏点后，ID还是空字符串？

A: 添加收藏点时，id和timeStamp会在添加成功后自动回填。确保检查返回值，只有返回1时才表示添加成功，此时poiInfo.id和poiInfo.timeStamp才会被填充。

const result: number = this.favoriteMgr.add(poiInfo);
if (result === 1) {
    // 此时 poiInfo.id 和 poiInfo.timeStamp 已被填充
    console.log(poiInfo.id);  // 有值
}

Q2: getAllFavPois()返回null是什么意思？

A: 返回null表示当前没有任何收藏点。这与返回空数组[]不同，需要特别处理：

const all: Array<FavoritePoiInfo> | null = this.favoriteMgr.getAllFavPois();
if (all !== null) {
    // 有收藏点，可以遍历
    all.forEach((poi: FavoritePoiInfo) => {
        // 处理每个收藏点
    });
} else {
    // 没有收藏点
    console.log("暂无收藏点");
}

Q3: 如何判断添加收藏点是否成功？

A: 根据add()方法的返回值判断：

const result: number = this.favoriteMgr.add(poiInfo);
if (result === 1) {
    // 成功
} else if (result === -1) {
    // 名称为空或重复
} else if (result === -2) {
    // 收藏点已满
} else {
    // 坐标无效或其他错误
}

Q4: 收藏点数据会丢失吗？

A: 不会。FavoriteManager内部实现了数据持久化，数据会自动保存到应用的文件目录。即使应用重启，收藏点数据仍然存在。

Q5: 可以设置收藏点的最大数量吗？

A: 可以。在底层配置中设置了maxFilesKeyNum: 501，表示最多可以保存501个收藏点。当达到上限时，add()方法会返回-2。

Q6: 如何避免重复添加相同名称的收藏点？

A: FavoriteManager会自动检查名称重复。如果添加的收藏点名称与已有收藏点重复，add()方法会返回-1。可以在添加前先检查：

const all: Array<FavoritePoiInfo> | null = this.favoriteMgr.getAllFavPois();
if (all !== null) {
    const exists: boolean = all.some((poi: FavoritePoiInfo) => poi.poiName === newName);
    if (exists) {
        console.log("名称已存在");
        return;
    }
}

Q7: 更新收藏点时需要注意什么？

A:

• 确保id参数与要更新的收藏点ID一致
• 更新时名称不能为空
• 坐标必须在有效范围内
• 更新成功后建议同步更新UI和地图标记

Q8: 什么时候需要调用destroy()？

A: 在组件的aboutToDisappear()生命周期中调用，释放资源。调用后单例实例会被置为null，下次使用需要重新调用getInstance()。

最后更新： 2025年11月24日 适用SDK版本： 2.0.3