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: 要更新的收藏点IDinfo: 新的收藏点信息

返回值：

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