查询与管理

本文介绍收藏项的查询、取消收藏、数量统计及云端同步等管理能力。

前置阅读：概述、收藏 POI

基本介绍

收藏数据写入本地后，应用可通过以下 API 进行查询与管理：

API	说明
listItems	按 Marker 查询收藏项列表
listMarkers	查询 Marker（收藏夹）列表
markerExists	检查用户自定义收藏夹（按名称）是否已存在
getItemsCount	获取指定 Marker 下的收藏项数量
unmarkItem	取消单个收藏
unmarkByMarkers	按 Marker 批量取消收藏（可一次清空收藏夹）
sync	将本地变更同步至云端

批量清空收藏夹请优先使用 unmarkByMarkers，参见 unmarkByMarkers。

查询收藏列表

listItems — 按 Marker 查询收藏项

常用过滤参数：

方法	说明
setMarkerId(String markerId)	按 Marker 过滤，如 FAVORITE、HOME
setMarkerType(MarkerType type)	SYSTEM 或 USER
setItemType(ItemType type)	收藏项类型，POI/地址使用 ENTITY
setCorrelationId(String id)	按实体 ID 精确查询
setName(String name)	按名称过滤

// 查询 FAVORITE 下的全部收藏
ListItemsResponse response = UserServiceAPI.getItemMarkAPI()
    .listItems()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemType(ItemType.ENTITY)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .execute();

ArrayList<Item> favorites = response.getItems();
for (Item item : favorites) {
    String name = item.getName();
    String correlationId = item.getCorrelationId();
    String metadata = item.getMetadata();
    // 渲染收藏列表
}

查询家/公司地址时，将 markerId 替换为 HOME 或 WORK 即可，参见 设置家与公司。

判断某个 POI 是否已收藏时，使用 listItems 并设置 setCorrelationId(entityId) 过滤，不要使用 markerExists。

listMarkers — 查询收藏夹列表

ListMarkersResponse response = UserServiceAPI.getItemMarkAPI()
    .listMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarkerType(MarkerType.USER)   // 查询用户自定义收藏夹
    .execute();

ArrayList<Marker> markers = response.getMarkers();

可按 markerId、label 进一步过滤。

getItemsCount — 获取收藏数量

execute() 直接返回 long，无 Response 包装类。

long count = UserServiceAPI.getItemMarkAPI()
    .getItemsCount()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemType(ItemType.ENTITY)
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .execute();

markerExists — 检查自定义收藏夹是否已存在

仅适用于用户自定义收藏夹（MarkerType.USER），按 label 匹配是否已存在同名收藏夹。不支持系统 Marker（如 FAVORITE、HOME）。

Marker marker = new Marker();
marker.setLabel("常去餐厅");
marker.setMarkerType(MarkerType.USER);

MarkerExistsResponse existsResponse = UserServiceAPI.getItemMarkAPI()
    .markerExists()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(marker)
    .execute();

boolean exists = existsResponse.isExists();

取消收藏

unmarkItem — 取消收藏关联

需要 markItem 返回的 itemId，以及对应的 markerId 和 markerType。

UnmarkResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkItem()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setItemId(itemId)                                // markItem 返回的 itemId
    .setMarkerId(SystemMarker.FAVORITE.name())
    .setMarkerType(MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

取消家/公司地址设置时，将 markerId 替换为 HOME 或 WORK。

说明：unmarkItem 仅取消 Item 与 Marker 的关联。若 Item 不再关联任何 Marker，是否从列表中消失取决于业务逻辑和同步状态。

unmarkByMarkers — 按 Marker 批量取消收藏

一次性取消指定 Marker 下全部 Item 的关联，支持单个或批量 Marker，无需循环 unmarkItem。

方法	说明
setMarker(String markerId, MarkerType type)	指定单个 Marker，仅取消 Item 关联
setMarker(String markerId, MarkerType type, boolean deleteMarker)	第三个参数为 true 时，在清空 Item 后删除用户 Marker
addMarker(MarkerSpec spec)	添加多个 Marker，批量处理
setNeedSync(boolean needSync)	是否同步至云端

MarkerSpec 字段：

字段	说明
markerId	Marker ID
markerType	SYSTEM 或 USER
deleteMarker	是否删除收藏夹；仅 USER 类型有效，系统 Marker 不可删除

返回值：UnmarkByMarkersResponse

字段	说明
getTotalClearedCount()	本次取消关联的 Item 总数
getResults()	每个 Marker 的处理结果列表
results[].getClearedCount()	该 Marker 下取消的 Item 数量
results[].isMarkerDeleted()	该 Marker 是否已删除

清空系统收藏夹（如 FAVORITE）

UnmarkByMarkersResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkByMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(SystemMarker.FAVORITE.name(), MarkerType.SYSTEM)
    .setNeedSync(true)
    .execute();

int cleared = response.getTotalClearedCount();

清空家/公司地址时，将 markerId 替换为 SystemMarker.HOME.name() 或 SystemMarker.WORK.name()。

清空并删除用户自定义收藏夹

UnmarkByMarkersResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkByMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setMarker(customMarkerId, MarkerType.USER, true)   // deleteMarker=true
    .setNeedSync(true)
    .execute();

boolean markerDeleted = response.getResults().get(0).isMarkerDeleted();

批量处理多个收藏夹

UnmarkByMarkersResponse response = UserServiceAPI.getItemMarkAPI()
    .unmarkByMarkers()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .addMarker(new MarkerSpec(SystemMarker.FAVORITE.name(), MarkerType.SYSTEM))
    .addMarker(new MarkerSpec(customMarkerId, MarkerType.USER, true))
    .setNeedSync(true)
    .execute();

说明：

• 系统 Marker 设置 deleteMarker=true 会返回 InvalidRequest。
• setNeedSync(true) 会同步 Item；若任一 Marker 为 USER 且 deleteMarker=true，还会同步 Marker。
• 同一 (markerId, markerType) 重复添加时，以首次出现的 deleteMarker 为准。
• unmarkItem 仅取消 Item 与指定 Marker 的关联；若 Item 还关联其他 Marker，仍会保留。

同步至云端

离线时收藏数据写入本地 SQLite；网络恢复后，通过 sync 将变更推送至 Telenav 云服务，实现多设备共享。

同步类型

SyncDataType	说明
ITEMS	同步收藏项（Item）
MARKERS	同步收藏夹（Marker）

代码示例

// 同步 Marker
SyncResponse markerSync = UserServiceAPI.getItemMarkAPI()
    .sync()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setSyncDataType(SyncDataType.MARKERS)
    .execute();

// 同步收藏项
SyncResponse itemSync = UserServiceAPI.getItemMarkAPI()
    .sync()
    .setSecureToken(secureToken)
    .setApplicationId(applicationId)
    .setApplicationSignature(applicationSignature)
    .setSyncDataType(SyncDataType.ITEMS)
    .execute();

同步建议

1. 收藏、取消收藏时设置 setNeedSync(true)，可在网络可用时自动触发同步。
2. 应用启动或网络恢复时，可主动调用 sync 拉取云端最新数据。
3. 删除未同步的本地 Marker 时需注意同步顺序，避免云端数据不一致。

完整管理流程示意

listMarkers / listItems          查询收藏夹与收藏项
        │
        ▼
markerExists / getItemsCount       检查状态与数量
        │
        ▼
unmarkItem / unmarkByMarkers         取消收藏（单个 / 按 Marker 批量）
        │
        ▼
sync(ITEMS / MARKERS)              同步至云端

注意事项

1. 所有请求需携带有效 secureToken；Token 过期时需先 刷新或重新登录。
2. listItems 返回的 Item 中，itemId 用于 unmarkItem；批量清空收藏夹请使用 unmarkByMarkers。
3. 离线场景下查询的是本地数据；联网并 sync 后可获取云端最新状态。

相关阅读

• 收藏 POI
• 设置家与公司
• 用户账号