# Mapbox 搜索整合技巧在应用程序中实现 Mapbox 搜索功能的专家指南。涵盖了从提出正确的发现问题、选择适当的搜索产品到遵循 Mapbox 搜索团队的最佳实践实施生产就绪集成的完整工作流程。 ## 使用此技能时用户说这样的话： *“我需要将搜索添加到我的地图” *“我的地图应用程序需要一个搜索栏” *“如何实现位置搜索？” *“我希望用户搜索地点/地址” *“我的应用程序需要地理编码” **此技能补充了`mapbox-search-patterns`：** * `mapbox-search-patterns` = 工具和参数选择 * `mapbox-search-integration` = 完整的实施工作流程 ## 发现阶段：提出正确的问题在开始编写代码之前，请询问以下问题以了解需求： ### 问题 1：用户在搜索什么？ **问：**“您希望用户搜索什么？” **常见答案和含义：** * **“地址”** → 关注地址地理编码，考虑搜索框 API 或地理编码 API * **“兴趣点/商家”** → POI搜索，使用Search Box API进行类别搜索 * **“地址和 POI”** → 搜索框 API * **“特定类型的 POI”**（餐厅、酒店等）→ 搜索框 API * **“国家、城市、邮政编码或社区”** → 地理编码 API * **“自定义位置”**（用户创建的位置）→ 可能需要自定义数据 + 搜索集成 **后续如果最初没有说明**：“您的用户是否在搜索兴趣点数据？餐馆、商店、企业类别？” **影响：** * **“是的，包含 POI”** → 使用搜索框 API * **“不，用户不需要 POI 搜索”** → 使用 Geocoding API ### 问题 2：地理范围是什么？ **问：**“用户将在哪里搜索？” **常见答案和含义：** * **“单一国家”**（例如“仅美国”）→使用 `country` 参数，效果更好，成本更低 * **“特定区域”** → 使用 `bbox` 参数进行边界框约束 * **“全球”** → 无国家限制，但可能需要语言参数 * **“多个特定国家”** → 使用 `country` 数组参数 **后续：**“您需要将结果限制在特定区域吗？” （送货区、服务区等） ### 问题3：搜索交互模式是什么？ **问：**“用户将如何与搜索交互？” **常见答案和含义：** * **“键入时搜索/自动完成”** → 对于搜索框 API 使用 `auto_complete: true`，或对于地理编码使用 `autocomplete=true`；还可以实现去抖动 * **“搜索按钮/最终查询”** → 可以使用任一 API，无需自动完成 * **“两者”**（自动完成 + 优化）→ 两阶段搜索，自动完成然后详细结果 * **“语音输入”** → 考虑语音到文本的集成，处理更长的查询 ### 问题4：什么平台？ **问：**“这适用于什么平台？” **常见答案和含义：** * **“Web 应用程序”** → Mapbox Search JS（最简单），或针对高级案例直接 API 调用 * **“iOS应用程序”** → 搜索iOS SDK（推荐），或高级案例直接API集成 * **“Android应用程序”** → 搜索Android SDK（推荐），或高级案例直接API集成 * **“多平台”** → 特定于平台的 SDK（推荐），或直接 API 方法以实现一致性 * **“React 应用程序”** → Mapbox Search JS React（最简单的 UI），或 Search JS Core 自定义 UI * **“Vue / Angular / 其他框架”** → Mapbox 搜索 JS Core 或 Web，或直接 API 调用 ### 问题 5：结果将如何使用？ **问：**“当用户选择结果时会发生什么？” **常见答案和含义：** * **“飞到地图上的位置”** → 需要坐标，地图集成 * **“显示详细信息/信息”** → 需要检索并显示结果属性 * **“填写表单字段”** → 需要解析地址组件 * **“开始导航”** → 需要坐标，与方向整合 * **“多重选择”** → 需要处理选择状态，可能显示标记 ### 问题6：预计使用量？ **问：**“您预计每月有多少次搜索？” **影响：** * **低容量** (< 10k) → 免费套餐足够，实施简单 * **中等容量** (10k-100k) → 考虑缓存，优化API调用 * **高容量** (> 100k) → 实施去抖动、缓存、批量操作、监控成本 ## 产品选择决策树根据发现的答案，推荐合适的产品： ### 搜索框 API **使用时间：** * 用户需要POI数据 * 需要基于会话的定价 *产品：** * **搜索框 API** (REST) - 直接 API 集成 * **Mapbox Search JS** (SDK) - 具有三个组件的 Web 集成： * **Search JS React** \- 通过 React 库与 UI 轻松集成搜索 * **Search JS Web** \- 通过 Web 组件与 UI 轻松集成搜索 * **搜索 JS Core** \- API 的 JavaScript（节点或 Web）包装器，构建您自己的 UI * **搜索 iOS SDK** \- 本机 iOS 集成 * **搜索 Android SDK** \- 原生 Android 集成 ### 地理编码 API **使用时间：** * 无需 POI 数据 * 需要永久地理编码（不是搜索） * 批量地理编码作业 ## 按平台划分的集成模式 **重要提示：** 始终更喜欢使用 SDK（Mapbox Search JS、适用于 iOS/Android 的搜索 SDK）而不是直接调用 API。 SDK 处理去抖动、会话令牌、错误处理并提供 UI 组件。仅对高级用例使用直接 API 调用。 ### 网页：Mapbox Search JS（推荐） #### 选项 1：搜索 JS React（最简单 - 带 UI 的 React 应用） **何时使用：** React应用程序，想要自动完成UI组件，最快实现 **安装：** npm 安装@mapbox/search-js-react **完整实施：** 从'@mapbox/search-js-react'导入{SearchBox}；从“mapbox-gl”导入mapboxgl；函数应用程序（）{ const [map, setMap] = React.useState(null); React.useEffect(() => { mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN'; const mapInstance = new mapboxgl.Map({ 容器：'地图'，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); setMap(mapInstance); }, []); const handleRetrieve = (结果) => { const [lng, lat] = result.features[0].geometry.coordinates; map.flyTo({ center: [lng, lat], Zoom: 14 }); new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map); }; 返回（

）； } #### 选项 2：搜索 JS Web（带有 UI 的 Web 组件） **何时使用：** Vanilla JavaScript、Web 组件或任何需要自动完成 UI 的框架 **完整实施：** <头> <正文>

<脚本> // 初始化地图 mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN'; 常量地图=新mapboxgl.Map({ 容器：'地图'，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); // 初始化搜索框 const search = new MapboxSearchBox(); search.accessToken = 'YOUR_MAPBOX_TOKEN'; // 关键：根据发现设置选项搜索.选项 = { 语言: 'en', Country: 'US', // 如果是单一国家（来自问题 2） proximity: 'ip', // 或者具体坐标 types: 'address,poi' // 基于问题 1 }; 搜索.mapboxgl = mapboxgl; 搜索.marker = true; // 在结果选择上自动添加标记 // 处理结果选择 search.addEventListener('检索', (事件) => { const 结果 = 事件.detail; // 飞向结果地图.flyTo({ 中心：结果.几何.坐标，变焦：15，本质：真实 }); // 可选：显示包含详细信息的弹出窗口新的mapboxgl.Popup() .setLngLat(结果.几何.坐标) .setHTML( `

${结果.properties.name}

${result.properties.full_address || ''}

` ） .addTo(地图); }); // 附加到 DOM document.getElementById('搜索').appendChild(搜索); **关键实施说明：** * ✅ 如果单一国家搜索，设置“国家”（更好的结果，更低的成本） * ✅ 根据用户搜索的内容设置“类型” * ✅ 使用 `proximity` 将结果偏向于用户位置 * ✅ 处理结果选择的“retrieve”事件 * ✅ 与地图集成（flyTo、标记、弹出窗口） #### 选项 3：搜索 JS Core（自定义 UI） **何时使用：** 需要自定义 UI 设计，完全控制 UX，适用于任何框架或 Node.js **安装：** npm 安装@mapbox/search-js-core **完整实施：** 从'@mapbox/search-js-core'导入{SearchSession}；从“mapbox-gl”导入mapboxgl； // 初始化搜索会话常量搜索 = 新的 SearchSession({ 访问令牌：'YOUR_MAPBOX_TOKEN' }); // 初始化地图 mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN'; 常量地图=新mapboxgl.Map({ 容器：'地图'，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); // 您的自定义搜索输入 const searchInput = document.getElementById('搜索输入'); const resultsContainer = document.getElementById('结果'); // 处理用户输入 searchInput.addEventListener('输入', async (e) => { const 查询 = e.target.value; if (query.length < 2) { 结果Container.innerHTML = ''; 返回； } // 获取建议（Search JS Core 处理去抖和会话令牌） const 响应 = 等待 search.suggest(查询, { 邻近度：map.getCenter().toArray(), 国家/地区: '美国', // 可选类型：['地址'，'poi'] }); // 渲染自定义结果 UI resultsContainer.innerHTML = 响应.建议 .地图( （建议）=> `

${suggestion.name}

${suggestion.place_formatted}

` ） .join(''); }); // 处理结果选择 resultsContainer.addEventListener('点击', async (e) => { const resultItem = e.target.closest('.result-item'); if (!resultItem) 返回； const mapboxId = resultItem.dataset.id; // 检索完整详细信息 const 结果 = 等待 search.retrieve(mapboxId); const 特征 = result.features[0]; const [lng, lat] = 特征.几何.坐标; // 更新地图 map.flyTo({ center: [lng, lat], Zoom: 15 }); new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map); // 清除搜索 searchInput.value = feature.properties.name; 结果Container.innerHTML = ''; }); **主要优点：** * ✅ 完全控制 UI/UX * ✅ Search JS Core 自动处理会话令牌 * ✅ 适用于任何框架（React、Vue、Angular 等） * ✅ 可在 Node.js 中用于服务器端搜索 #### 选项 4：直接 API 集成（高级 - 最后的手段） **何时使用：** SDK 不支持的非常具体的要求，或者 Search JS Core 不适合的服务器端集成 **重要提示：** 仅当 SDK 不能满足您的需求时才使用直接 API 调用。您需要手动处理去抖和会话令牌。 **何时使用：** 自定义UI、框架集成、需要完全控制 **带去抖动的完整实现：** 从“mapbox-gl”导入mapboxgl；类 MapboxSearch { 构造函数（accessToken，选项= {}）{ this.accessToken = accessToken; 这个.选项= { 国家: 选项.国家 || null, // 例如，“美国” 语言：选项.语言 || '恩', 邻近度： options.proximity || 'ip', 类型：选项.类型 || '地址，poi', 限制：选项.限制 || 5、 ...选项 }; this.debounceTimeout = null; this.sessionToken = this.generateSessionToken(); } 生成会话令牌（）{ 返回 `${Date.now()}-${Math.random().toString(36).substring(7)}`; } // 关键：反跳以避免 API 垃圾邮件异步搜索（查询，回调，debounceMs = 300）{ 清除超时(this.debounceTimeout); this.debounceTimeout = setTimeout(async () => { const 结果 = 等待 this.performSearch(query); 回调（结果）； }, debounceMs); } 异步执行搜索（查询）{ if (!query || query.length < 2) return []; const params = new URLSearchParams({ 问：查询， access_token: this.accessToken, session_token: this.sessionToken, 语言：this.options.language，限制：this.options.limit }); // 添加可选参数 if (this.options.country) { params.append('国家', this.options.country); } if (this.options.types) { params.append('types', this.options.types); } if (this.options.proximity && this.options.proximity !== 'ip') { params.append('proximity', this.options.proximity); } 尝试{ const 响应 = 等待 fetch(`https://api.mapbox.com/search/searchbox/v1/suggest?${params}`); 如果（！response.ok）{ throw new Error(`搜索 API 错误：${response.status}`); } const data =等待response.json(); 返回数据.建议 || []； } 捕获（错误）{ console.error('搜索错误：', error); 返回 []; } } 异步检索（suggestionId）{ const params = new URLSearchParams({ access_token: this.accessToken, session_token: this.sessionToken }); 尝试{ const 响应 = 等待 fetch(`https://api.mapbox.com/search/searchbox/v1/retrieve/${suggestionId}?${params}`); 如果（！response.ok）{ throw new Error(`检索 API 错误：${response.status}`); } const data =等待response.json(); // 会话在检索时结束 - 为下一次搜索生成新令牌 this.sessionToken = this.generateSessionToken(); 返回数据.features[0]; } 捕获（错误）{ console.error('检索错误：', error); 返回空值； } } } // 使用示例 const search = new MapboxSearch('YOUR_MAPBOX_TOKEN', { Country: 'US', // 基于发现问题 2 types: 'poi', // 基于发现问题 1 proximity: [-122.4194, 37.7749] // 或者 'ip' 表示用户位置 }); // 附加到输入字段 const input = document.getElementById('搜索输入'); const resultsContainer = document.getElementById('搜索结果'); input.addEventListener('输入', (e) => { const 查询 = e.target.value; 搜索.搜索（查询，（结果）=> { 显示结果（结果）； }); }); 函数显示结果（结果）{ resultsContainer.innerHTML = 结果 .地图( （结果）=>`

${结果.名称}

${结果.place_formatted || ''}

` ） .join(''); // 处理结果选择 resultsContainer.querySelectorAll('.result').forEach((el) => { el.addEventListener('点击', async () => { const feature = wait search.retrieve(el.dataset.id); 处理结果选择（特征）； }); }); } 函数handleResultSelection（特征）{ const [lng, lat] = 特征.几何.坐标; // 将地图飞行到结果地图.flyTo({ 中心：[经纬度]，变焦：15 }); // 添加标记 new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map); // 关闭结果结果Container.innerHTML = ''; 输入.值=特征.属性.名称; } **关键实施细节：** 1. ✅ **去抖动** ：用户停止输入后等待 300 毫秒再调用 API 2. ✅ **会话令牌** ：使用相同的令牌进行建议+检索，之后生成新的令牌 3. ✅ **错误处理**：优雅地处理API错误 4. ✅ **参数优化** : 只发送你需要的参数 5. ✅ **结果显示** : 显示姓名+格式化地址 6. ✅ **选择处理**：检索选择的完整功能 ### React 集成模式 **最佳实践：** 使用 Search JS React 实现最简单的实现，或使用 Search JS Core 实现自定义 UI。 #### 选项 1：搜索 JS React（推荐 - 最简单）从'@mapbox/search-js-react'导入{SearchBox}；从“mapbox-gl”导入mapboxgl；从'react'导入{useState}；函数 MapboxSearchComponent() { const [map, setMap] = useState(null); 使用效果（（）=> { const mapInstance = new mapboxgl.Map({ 容器：'地图'，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); setMap(mapInstance); }, []); const handleRetrieve = (结果) => { const [lng, lat] = result.features[0].geometry.coordinates; map.flyTo({ center: [lng, lat], Zoom: 14 }); new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map); }; 返回（

<搜索框 accessToken =“YOUR_MAPBOX_TOKEN” onRetrieve={handleRetrieve} placeholder=“搜索地点” 选项={{ 国家/地区: '美国', // 可选类型：'地址，POI' }} />

）； } **好处：** * ✅ 提供完整的 UI 组件 * ✅ 无需手动去抖 * ✅ 无需手动会话令牌管理 * ✅ 开箱即可投入生产 #### 选项 2：搜索 JS Core（自定义 UI）从 'react' 导入 { useState, useEffect }; 从'@mapbox/search-js-core'导入{SearchSession}；从“mapbox-gl”导入mapboxgl；函数 MapboxSearchComponent({ 国家/地区, 类型 = '地址,poi' }) { const [查询，setQuery] = useState(''); const [结果，setResults] = useState([]); const [isLoading, setIsLoading] = useState(false); // Search JS Core 自动处理去抖和会话令牌常量 searchSession = 新 SearchSession({ 访问令牌：'YOUR_MAPBOX_TOKEN' }); 使用效果（（）=> { const PerformSearch = async () => { if (!query || query.length < 2) { 设置结果（[]）；返回； } setIsLoading(true); 尝试{ const 响应 = 等待 searchSession.suggest(query, { 国家, 类型，限制：5 }); setResults(response.suggestions || []); } 捕获（错误）{ console.error('搜索错误：', error); 设置结果（[]）； }最后{ setIsLoading(假); } }; 执行搜索（）； }, [查询]); const handleResultClick = 异步（建议）=> { 尝试{ const 结果 = 等待 searchSession.retrieve(建议); const 特征 = result.features[0]; // 处理结果（飞到位置、添加标记等） onResultSelect(特征); setQuery(feature.properties.name); 设置结果（[]）； } 捕获（错误）{ console.error('检索错误：', error); } }; 返回（

<输入类型=“文本” 值={查询} onChange={(e) => setQuery(e.target.value)} placeholder="搜索地点..." 类名=“搜索输入” /> {isLoading &&

正在搜索...

} {结果.长度> 0 && (

{结果.map((结果) => (

handleResultClick(result)}> {结果.名称} {result.place_formatted &&

{result.place_formatted}

}

))}

)}

）； } **好处：** * ✅ 完全掌控UI设计 * ✅ Search JS Core 自动处理去抖 * ✅ Search JS Core 自动处理会话令牌 * ✅ 比直接 API 调用更干净的代码 **注意：** 对于 React 应用程序，首选 Search JS React（选项 1），除非您需要完全自定义的 UI 设计。 ### iOS：搜索 iOS SDK（推荐） #### 选项 1：使用 UI 搜索 SDK（最简单） **何时使用：** iOS 应用程序，需要预构建的搜索 UI，最快的实施 **安装：** // 添加到 Package.swift 或 SPM 依赖项：[ .package（url：“https://github.com/mapbox/mapbox-search-ios.git”，来自：“2.0.0”） ] **使用内置 UI 完成实现：** 导入 MapboxSearch 导入 Mapbox 地图类 SearchViewController: UIViewController { 私有变量 searchController：MapboxSearchController！私有变量mapView：MapView！覆盖 func viewDidLoad() { super.viewDidLoad() 设置映射() setupSearchWithUI() } 函数setupMap() { mapView = MapView(框架: view.bounds) view.addSubview(mapView) } 函数 setupSearchWithUI() { // MapboxSearchController 自动提供完整的 UI 搜索控制器 = MapboxSearchController() searchController.delegate = self // 呈现搜索 UI 存在（searchController，动画：true） } } 扩展 SearchViewController: SearchControllerDelegate { func searchResultSelected(_ searchResult: SearchResult) { // SDK处理所有搜索交互 // 只响应选择 mapView.camera.fly（到：CameraOptions（中心：搜索结果.坐标，变焦：15 ））让注释= PointAnnotation（坐标：searchResult.坐标） mapView.annotations.pointAnnotations = [注释] 解雇（动画：true） } } #### 选项 2：搜索 SDK 核心（自定义 UI） **何时使用：** 需要自定义 UI，与 UISearchController 集成，完全控制 UX **完整实施：** 导入 MapboxSearch 导入 Mapbox 地图类 SearchViewController: UIViewController { private var searchEngine: 搜索引擎！私有变量mapView：MapView！覆盖 func viewDidLoad() { super.viewDidLoad() // 初始化搜索引擎（SDK 处理去抖和会话令牌） searchEngine = SearchEngine(accessToken: "YOUR_MAPBOX_TOKEN") 设置搜索栏() 设置映射() } 函数设置搜索栏（）{ 让 searchController = UISearchController(searchResultsController: nil) searchController.searchResultsUpdater = self searchController.obscuresBackgroundDuringPresentation = false 导航项.searchController = searchController } 函数setupMap() { mapView = MapView(框架: view.bounds) view.addSubview(mapView) } } 扩展 SearchViewController: UISearchResultsUpdating { func updateSearchResults(for searchController: UISearchController) { Guard let query = searchController.searchBar.text, !query.isEmpty else { 返回 } // Search SDK自动处理去抖动 searchEngine.search(query: query) { [weak self] 结果切换结果{ 案例.成功（让结果）： self?.displayResults(结果) 案例.失败（让错误）： print("搜索错误：\(错误)") } } } func displayResults(_ 结果: [搜索结果]) { // 在自定义表格视图中显示结果 // 当用户选择结果时：处理结果选择（结果[0]） } func handleResultSelection(_ 结果：SearchResult) { mapView.camera.fly（到：CameraOptions（中心：结果.坐标，变焦：15 ））让注释= PointAnnotation（坐标：结果.坐标） mapView.annotations.pointAnnotations = [注释] } } #### 选项 3：直接 API 集成（高级） **何时使用：** 非常具体的要求，服务器端 iOS 后端 **重要：** 仅当 SDK 不能满足您的需求时才使用。您必须手动处理去抖和会话令牌。 // 直接 API 调用 - 请参阅 Web 直接 API 示例 // 不推荐 iOS - 使用搜索 SDK ### Android：搜索 Android SDK（推荐） #### 选项 1：使用 UI 搜索 SDK（最简单） **何时使用：** Android 应用程序，需要预构建的搜索 UI，最快的实施 **安装：** // 添加到 build.gradle 依赖项{ 实现 'com.mapbox.search:mapbox-search-android-ui:2.0.0' 实现 'com.mapbox.maps:android:11.0.0' } **使用内置 UI 完成实现：** 导入 com.mapbox.search.ui.view.SearchBottomSheetView 导入 com.mapbox.maps.MapView 类 SearchActivity : AppCompatActivity() { private Lateinit var searchView：SearchBottomSheetView private Lateinit var mapView: MapView 覆盖 fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_search) mapView = findViewById(R.id.map_view) // SearchBottomSheetView 自动提供完整的 UI searchView = findViewById(R.id.search_view) searchView.initializeSearch( 保存实例状态， SearchBottomSheetView.Configuration() ） // 处理结果选择 searchView.addOnSearchResultClickListener { searchResult -> // SDK处理所有搜索交互 val 坐标 = searchResult. 坐标 mapView.getMapboxMap().flyTo( CameraOptions.Builder() .center(Point.fromLngLat(坐标.经度,坐标.纬度)) .缩放(15.0) .build() ）搜索视图.隐藏() } } } #### 选项 2：搜索 SDK 核心（自定义 UI） **何时使用：** 需要自定义 UI，与 SearchView 集成，完全控制 UX **完整实施：** 导入 com.mapbox.search.SearchEngine 导入 com.mapbox.search.SearchEngineSettings 导入 com.mapbox.search.SearchOptions 导入 com.mapbox.maps.MapView 类 SearchActivity : AppCompatActivity() { private Lateinit var searchEngine: 搜索引擎 private Lateinit var mapView: MapView 覆盖 fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // 初始化搜索引擎（SDK 处理去抖和会话令牌）搜索引擎 = 搜索引擎.createSearchEngine( 搜索引擎设置（“YOUR_MAPBOX_TOKEN”））设置搜索视图() 设置映射() } 私人乐趣 setupSearchView() { val searchView = findViewById(R.id.search_view) searchView.setOnQueryTextListener(对象：SearchView.OnQueryTextListener { 覆盖 fun onQueryTextSubmit(query: String): Boolean { 执行搜索（查询）返回真 } 覆盖 fun onQueryTextChange(newText: String): Boolean { if (newText.length >= 2) { // Search SDK自动处理去抖动执行搜索（新文本） } 返回真 } }) } 私人乐趣执行搜索（查询：字符串）{ val 选项 = 搜索选项( 国家 = listOf("美国"), 限制 = 5 ） searchEngine.search(查询, 选项) { 结果 -> results.onSuccess { 搜索结果 -> 显示结果（搜索结果） }.onFailure { 错误 -> Log.e("搜索", "错误：$error") } } } 私人乐趣显示结果（结果：List ）{ // 在自定义RecyclerView中显示处理结果选择（结果[0]） } 私人乐趣handleResultSelection（结果：SearchResult）{ val 坐标 = 结果.坐标 mapView.getMapboxMap().flyTo( CameraOptions.Builder() .center(Point.fromLngLat(坐标.经度,坐标.纬度)) .缩放(15.0) .build() ） } } #### 选项 3：直接 API 集成（高级） **何时使用：** 非常具体的要求，服务器端 Android 后端 **重要：** 仅当 SDK 不能满足您的需求时才使用。您必须手动处理去抖和会话令牌。 // 直接 API 调用 - 请参阅 Web 直接 API 示例 // 不推荐用于 Android - 使用搜索 SDK ### Node.js：Mapbox Search JS 核心（推荐） #### 选项1：搜索JS Core（推荐） **何时使用：** 服务器端搜索、后端 API、无服务器功能 **安装：** npm 安装@mapbox/search-js-core **完整实施：** 从'@mapbox/search-js-core'导入{SearchSession}； // 初始化搜索会话（自动处理会话令牌）常量搜索 = 新的 SearchSession({ accessToken：process.env.MAPBOX_TOKEN }); // Express.js API 端点示例 app.get('/api/search', async (req, res) => { const { 查询、邻近度、国家/地区 } = req.query; 尝试{ // 获取建议（Search JS Core 处理会话管理） const 响应 = 等待 search.suggest(查询, { 接近度：接近度？ proximity.split(',').map(Number) ：未定义，国家：国家，限制：10 }); res.json(响应.建议); } 捕获（错误）{ res.status(500).json({ 错误: error.message }); } }); // 检索所选结果的完整详细信息 app.get('/api/search/:id', async (req, res) => { 尝试{ const 结果 = 等待 search.retrieve(req.params.id); res.json(结果.features[0]); } 捕获（错误）{ res.status(500).json({ 错误: error.message }); } }); **主要优点：** * ✅ Search JS Core 自动处理会话令牌 * ✅ 非常适合无服务器（Vercel、Netlify、AWS Lambda） * ✅ 与浏览器搜索 JS Core 相同的 API * ✅ 无需手动去抖（在 API 网关级别处理） #### 选项 2：直接 API 集成（高级） **何时使用：** 非常具体的要求，需要 Search JS Core 中没有的功能 **实施：** 从“节点获取”导入获取；异步函数 searchPlaces(query, options = {}) { const params = new URLSearchParams({ 问：查询， access_token：process.env.MAPBOX_TOKEN， session_token:generateSessionToken(), // 您必须管理它 ...选项 }); const 响应 = 等待 fetch(`https://api.mapbox.com/search/searchbox/v1/suggest?${params}`); 返回response.json(); } **重要提示：** 仅当 Search JS Core 不能满足您的需求时才使用直接 API 调用。您需要手动处理会话令牌。 ## 最佳实践：“好的部分” ### 1\.去抖动（对于自动完成至关重要） **注意：** 仅当您直接调用 API 时才需要考虑去抖动。 Mapbox Search JS 和搜索 SDK 自动处理去抖。 **问题：** 每次击键 = API 调用 = 昂贵 + 缓慢 **解决方案：** 等待用户停止输入（用于直接 API 集成）让debounce超时；函数 debouncedSearch(查询) { 清除超时（debounceTimeout）； debounceTimeout = setTimeout(() => { 执行搜索（查询）； }, 300); // 300ms 对于大多数用例来说是最佳的 } **为什么是 300 毫秒？** * 速度足够快，感觉反应灵敏 * 足够慢以避免垃圾邮件 * 行业标准（Google 使用约 300 毫秒） ### 2\.会话令牌管理 **注意：** 仅当您直接调用 API 时才需要考虑会话令牌。 Mapbox Search JS 和适用于 iOS/Android 的搜索 SDK 自动处理会话令牌。 **问题：** Search Box API 按会话收费，而不是按请求收费 **什么是会话？** * 从第一个建议请求开始 * 以检索请求结束 * 对会话中的所有请求使用相同的令牌 **实现（仅限直接API调用）：** 类搜索会话{ 构造函数（）{ this.token = this.generateToken(); } 生成令牌（）{ 返回 `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`; } 异步建议（查询）{ // 对所有建议请求使用 this.token return fetch(`...?session_token=${this.token}`); } 异步检索（id）{ const result = wait fetch(`...?session_token=${this.token}`); // 会话结束 - 生成新令牌 this.token = this.generateToken(); 返回结果； } } **成本影响：** * ✅ 正确：1 次会话 = 无限制建议 + 1 次检索 = 1 次收费 * ❌错误：没有会话令牌=每个请求单独收费 ### 3\.地理过滤 **尽可能设置位置上下文：** // 好：特定国家 { 国家：“美国”； } // 好：接近用户 { 接近度：[-122.4194, 37.7749]； } // GOOD：服务区域的边界框 { bbox: [-122.5, 37.7, -122.3, 37.9]; } // 不好：没有地理背景 { } // 返回全局结果，速度较慢，相关性较低 **提示：** 使用[位置助手工具]() 轻松计算服务区域的边界框。 **为什么重要：** * ✅ 更好的结果相关性 * ✅ 更快的响应时间 * ✅ 降低歧义 * ✅ 更好的用户体验 ### 4\.错误处理 **处理所有失败案例：** 异步函数执行搜索（查询）{ 尝试{ const 响应 = 等待 fetch(searchUrl); // 检查 HTTP 状态如果（！response.ok）{ if (response.status === 429) { // 速率限制 showError('请求过多，请稍等。'); 返回 []; } else if (response.status === 401) { // 无效令牌 showError('搜索不可用，请检查配置。'); 返回 []; } 否则{ // 其他错误 showError('搜索失败，请重试。'); 返回 []; } } const data =等待response.json(); // 检查结果 if (!data.suggestions || data.suggestions.length === 0) { showMessage('未找到结果。尝试不同的搜索。'); 返回 []; } 返回数据.建议； } 捕获（错误）{ // 网络错误 console.error('搜索错误：', error); showError('网络错误。请检查您的连接。'); 返回 []; } } ### 5\.结果显示用户体验 **显示足够的上下文以消除歧义：**

星巴克

加利福尼亚州旧金山主街 123 号

咖啡店

**不只是：**

星巴克

### 6\.加载状态 **始终显示加载反馈：** 函数执行搜索（查询）{ 显示加载旋转器（）；获取（搜索网址） .then((响应) => response.json()) .then((数据) => { 隐藏LoadingSpinner(); 显示结果（数据.建议）； }) .catch((错误) => { 隐藏LoadingSpinner(); showError('搜索失败'); }); } ### 7\.无障碍 **使搜索可通过键盘导航：**

结果 1
结果 2

**键盘支持：** * ⬆️⬇️ 箭头键：导航结果 * 输入：选择结果 * 逃脱：关闭结果 ### 8\.移动优化 **iOS/Android 特定注意事项：** // iOS：调整键盘通知中心.default.addObserver( forName: UIResponder.keyboardWillShowNotification, 对象：无，队列：.main ) { 通知中 // 调整键盘视图 } // 处理外部点击以关闭让tapGesture = UITapGestureRecognizer（目标：self，操作：#selector（dismissKeyboard）） view.addGestureRecognizer(tapGesture) **使触摸目标足够大：** * 最小：44x44pt (iOS) / 48x48dp (Android) * 确保结果之间有足够的间距 ### 9\.缓存（适用于大容量应用程序） **缓存最近/热门搜索：** 类搜索缓存{ 构造函数（最大大小= 50）{ this.cache = new Map(); this.maxSize = maxSize; } 获取（查询）{ const key = query.toLowerCase(); 返回 this.cache.get(key); } 设置（查询，结果）{ const key = query.toLowerCase(); // LRU 驱逐 if (this.cache.size >= this.maxSize) { const firstKey = this.cache.keys().next().value; this.cache.delete(firstKey); } this.cache.set(key, { 结果，时间戳：Date.now() }); } isValid(条目, maxAgeMs = 5 * 60 * 1000) { 返回条目 && Date.now() - entry.timestamp < maxAgeMs; } } // 用法 const 缓存 = new SearchCache(); 异步函数搜索（查询）{ const 缓存=cache.get(query); if (cache.isValid(缓存)) { 返回缓存的结果； } 常量结果=等待执行APISearch（查询）；缓存.set（查询，结果）；返回结果； } ### 10\.令牌安全 **关键：正确确定令牌范围：** // 创建仅具有搜索范围的令牌 // 在 Mapbox 仪表板或通过 API： { “范围”：[ “搜索：阅读”， "styles:read", // 仅当显示地图时 "fonts:read" // 仅当显示地图时 ], “允许的网址”：[ “https://yourdomain.com/*” ] } **从不：** * ❌ 在客户端代码中使用秘密令牌 (sk.*) * ❌ 给予代币比需要更多的范围 * ❌ 跳过公共代币的 URL 限制详情请参阅“mapbox-token-security”技能。 ## 常见陷阱以及如何避免它们 ### ❌陷阱1：没有去抖 **问题：** input.addEventListener('输入', (e) => { 执行搜索（e.target.value）； // 每次击键都会调用 API！ }); **影响：** * 🔥 昂贵（数百次不必要的 API 调用） * 🐌 慢（竞争条件、过时的结果） * 💥 速率限制（429 个错误） **解决方案：** 始终去抖（请参阅最佳实践#1） ### ❌陷阱 2：忽略会话令牌 **问题：** // 无会话令牌 = 每个请求单独收费 fetch('...建议?q=query&access_token=xxx'); **影响：** * 💰 成本比必要的多 10-100 倍 * 预算因多余费用而被浪费 **解决方案：** 使用会话令牌（请参阅最佳实践 #2） ### ❌陷阱 3：没有地理背景 **问题：** // 全局搜索“Paris” { q: '巴黎'; } // 法国巴黎？巴黎、德克萨斯？巴黎、肯塔基？ **影响：** * 😕 令人困惑的结果（错误的国家） * 🐌 反应较慢 * 😞 用户体验差 **解决方案：** // 好多了 { q: '巴黎', 国家: '美国', 邻近度: user_location } ### ❌陷阱 4：糟糕的移动用户体验 **问题：**

搜索结果

**影响：** * 😤 点击时令人沮丧 * 🎯 意外选择 * ⭐ 差评 **解决方案：** .搜索结果{ 最小高度：48px； /* Android 最低 */ 内边距：12px；边距：4px 0； } ### ❌陷阱 5：不处理空结果 **问题：** // 只显示空容器显示结果([]); // 用户看到空白区域 - 正在加载吗？破碎的？ **影响：** * ❓ 用户困惑 * 🤔 有效吗？ **解决方案：** if (结果.length === 0) { showMessage('未找到结果。尝试不同的搜索词。'); } ### ❌陷阱 6：慢速网络阻塞 **问题：** // 无超时 = 在慢速网络上永远等待等待获取（searchUrl）； **影响：** * ⏰ 看起来冻结 * 😫 用户沮丧 **解决方案：** const 控制器 = new AbortController(); const 超时 = setTimeout(() =>controller.abort(), 5000); fetch(searchUrl, { signal:controller.signal }).finally(() =>clearTimeout(timeout)); ### ❌陷阱 7：忽略结果类型 **问题：** // 同等对待所有结果显示结果(结果.名称); // 但这是一个地址吗？兴趣点？地区？ **影响：** * 🤷 不清楚选择了什么 * 🗺️ 错误的缩放级别 * 📍 不适当的标记 **解决方案：** 函数处理结果（结果）{ const 类型 = 结果.feature_type; 如果（类型 === 'poi'）{ map.flyTo({ 中心: 坐标, 缩放: 17 }); // 关闭缩放添加POIMarker（结果）； } else if (type === '地址') { map.flyTo({ 中心: 坐标, 缩放: 16 }); 添加地址标记（结果）； } else if (type === '地点') { map.flyTo({ 中心: 坐标, 缩放: 12 }); // 更广阔的城市视野 } } ### ❌陷阱 8：竞争条件 **问题：** // 快速输入：“san francisco” // API 响应无序到达： // “san f”结果在“san francisco”结果之后到达 **影响：** * 🔀 显示错误结果 * 😵 令人困惑的用户体验 **解决方案：** 让搜索计数器 = 0; 异步函数执行搜索（查询）{ const currentSearch = ++searchCounter; const results = 等待 fetchResults(query); // 仅当这仍然是最新搜索时才显示 if (currentSearch === searchCounter) { 显示结果（结果）； } } ## 框架特定指南 ### React 最佳实践 **最佳实践：** 使用 Search JS React 或 Search JS Core，而不是通过直接 API 调用构建自定义挂钩。 #### 选项 1：使用 Search JS React（推荐）从'@mapbox/search-js-react'导入{SearchBox}； // 最简单 - 只需使用 SearchBox 组件函数 MyComponent() { 返回（ <搜索框访问令牌=“YOUR_TOKEN” onRetrieve={(结果) => { // 处理结果 }} 选项={{ 国家：“美国”，类型：'地址，POI' }} /> ）； } #### 选项 2：使用 Search JS Core 自定义 Hook 从 'react' 导入 { useState, useCallback, useRef, useEffect }; 从'@mapbox/search-js-core'导入{SearchSession}； // 使用 Search JS Core 的自定义钩子（处理去抖动和会话令牌）函数 useMapboxSearch(accessToken, options = {}) { const [结果，setResults] = useState([]); const [isLoading, setIsLoading] = useState(false); const [错误，setError] = useState(null); // Search JS Core 自动处理会话令牌 const searchSessionRef = useRef(null); 使用效果（（）=> { searchSessionRef.current = new SearchSession({ accessToken }); }, [accessToken]); 常量搜索 = useCallback( 异步（查询）=> { if (!query || query.length < 2) { 设置结果（[]）；返回； } setIsLoading(true); 设置错误（空）；尝试{ // 搜索 JS Core 处理去抖和会话令牌 const 响应 = 等待 searchSessionRef.current.suggest(query, options); setResults(response.suggestions || []); } 捕获（错误）{ setError(err.message); 设置结果（[]）； }最后{ setIsLoading(假); } }, [选项] ）； const检索= useCallback（异步（建议）=> { 尝试{ // Search JS Core 自动处理会话令牌 const 结果 = 等待 searchSessionRef.current.retrieve(建议); 返回结果.features[0]; } 捕获（错误）{ setError(err.message); 抛出错误； } }, []); 返回{结果，isLoading，错误，搜索，检索}； } **使用 Search JS Core 的好处：** * ✅ 无需手动会话令牌管理 * ✅ 无需手动去抖 * ✅ 不需要竞争条件处理（SDK 处理它） * ✅ 更干净、更简单的代码 * ✅ 内置生产就绪错误处理 ### Vue Composition API（使用 Search JS Core - 推荐）从 'vue' 导入 { ref, watch }; 从'@mapbox/search-js-core'导入{SearchSession}；导出函数 useMapboxSearch(accessToken, options = {}) { const 查询 = ref(''); 常量结果 = ref([]); const isLoading = ref(false); // 使用 Search JS Core - 自动处理去抖动和会话令牌 const searchSession = new SearchSession({ accessToken }); const PerformSearch = async (searchQuery) => { if (!searchQuery || searchQuery.length < 2) { 结果.值=[]; 返回; } isLoading.value = true; 尝试{ // 搜索 JS Core 处理去抖和会话令牌 const 响应 = 等待 searchSession.suggest(searchQuery, 选项); 结果.值 = 响应.建议 || []； } 捕获（错误）{ console.error('搜索错误：', error); 结果.值=[]; }最后{ isLoading.value = false; } }; // 观察查询变化（Search JS Core 处理去抖动）手表（查询，（newQuery）=> { 执行搜索(newQuery); }); const 检索 = 异步（建议）=> { // Search JS Core 自动处理会话令牌 const feature = wait searchSession.retrieve(建议); 返回功能； }; 返回{ 查询，结果，正在加载，检索 }; } **主要优点：** * ✅ Search JS Core 自动处理去抖（不需要 lodash） * ✅ 自动管理会话令牌（无需手动生成令牌） * ✅ 更简单的代码，更少的依赖 * ✅ 相同的 API 在浏览器和 Node.js 中工作 ## 测试策略 ### 单元测试 // 用于测试的模拟获取 global.fetch = jest.fn(); 描述('MapboxSearch', () => { 之前（（）=> { fetch.mockClear(); }); test('消除搜索请求', async () => { const search = new MapboxSearch('假令牌'); // 快速搜索搜索.搜索('san'); search.search('san f'); search.search('san fr'); search.search('旧金山'); // 等待去抖等待新的 Promise((resolve) => setTimeout(resolve, 400)); // 应该只进行一次 API 调用期望（获取）.toHaveBeenCalledTimes（1）； }); test('处理空结果', async () => { fetch.mockResolvedValue({ 好的：是的， json: async () => ({ 建议: [] }) }); const search = new MapboxSearch('假令牌'); const results = wait search.performSearch('xyz'); 期望(结果).toEqual([]); }); test('处理 API 错误', async () => { fetch.mockResolvedValue({ 好的：假的，状态：429 }); const search = new MapboxSearch('假令牌'); const results = wait search.performSearch('test'); 期望(结果).toEqual([]); }); }); ### 集成测试描述（'搜索集成'，（）=> { test('完整的搜索流程', async () => { const search = new MapboxSearch(process.env.MAPBOX_TOKEN); // 执行搜索 const suggest = wait search.performSearch('旧金山'); 期望(suggestions.length).toBeGreaterThan(0); // 获取第一个结果 const feature = wait search.retrieve(suggestions[0].mapbox_id); 期望（特征.几何.坐标）.toBeDefined（）; Expect(feature.properties.name).toBe('旧金山'); }); }); ## 监控和分析 ### 跟踪关键指标 // 跟踪搜索使用情况函数 trackSearch(查询, 结果计数) { Analytics.track('搜索执行', { query_length：查询长度， results_count：结果计数， had_results：结果数> 0 }); } // 轨道选择函数 trackSelection(结果, 位置) { Analytics.track('search_result_selected', { 结果类型：结果.特征类型，结果位置：位置， had_address:!!result.properties.full_address }); } // 跟踪错误函数 trackError(errorType, 查询) { Analytics.track('搜索错误', { error_type：错误类型， query_length: 查询长度 }); } ### 监控问题 * 📊 零结果率（应< 20%） * ⚡ 平均响应时间 * 💥 错误率 * 🎯 选择率（用户选择与放弃） * 💰 API 使用与预算 ## 清单：生产就绪搜索启动之前，请验证： **配置：** * 令牌范围正确（搜索：只读） * 配置URL限制 * 地理过滤集（国家、邻近地区或 bbox） * 基于用例的类型参数集 * 如果需要的话设置语言参数 **实施：** * 实现去抖动（建议 300ms） * 正确使用会话令牌 * 所有失败情况的错误处理 * 显示加载状态 * 优雅地处理空结果 * 防止竞争条件 **用户体验：** * 触摸目标至少 44pt/48dp * 结果显示了足够的上下文（姓名+地址） * 键盘导航有效 * 辅助功能属性设置 * 正确处理移动键盘 **性能：** * 实施缓存（如果容量大） * 请求超时设置 * 获取最少的数据 * 捆绑包大小优化 **测试：** * 核心逻辑的单元测试 * 与真实API的集成测试 * 在慢速网络上测试 * 使用各种查询类型进行测试 * 移动设备测试 **监控：** * 分析跟踪设置 * 配置错误日志记录 * 到位的使用监控 * 配置预算警报 ## 与其他技能的整合 **适用于：** * **mapbox-search-patterns** ：参数选择和优化 * **mapbox-web-integration-patterns** ：特定于框架的模式 * **mapbox-token-security** ：令牌管理和安全 * **mapbox-web-performance-patterns** ：优化搜索性能 ## 资源 * [搜索框API文档]() * [地理编码 API 文档]() * [Mapbox 搜索 JS]() * [搜索 JS React]() * [搜索 JS Web]() * [搜索 JS 核心]() * [iOS 搜索 SDK]() * [Android 搜索 SDK]() * [位置辅助工具]() \- 计算边界框 ## 快速决策指南 **用户说：“我需要位置搜索”** 1. **提出发现问题**（上述问题 1-6） 2. **推荐产品：** * 搜索框 API 或地理编码 API * 平台SDK（移动端） 3. **实施方式：** * ✅ 去抖 * ✅ 会话令牌 * ✅ 地理过滤 * ✅ 错误处理 * ✅ 良好的用户体验 4. **彻底测试** 5. **生产中的监控** **记住：** 最好的搜索实现首先提出正确的问题，然后准确构建用户需要的内容 - 不多也不少。

Mapbox 搜索集成

包含技能