此页面由 Cloud Translation API 翻译。

自动补全（新）

请选择平台： Android iOS JavaScript 网络服务

欧洲经济区 (EEA) 开发者

自动补全（新）会针对包含文本搜索字符串和用于控制搜索区域的地理边界的请求返回地点预测结果。自动补全功能可以根据输入内容的完整字词和子字符串进行匹配，从而解析地点名称、地址和 Plus Codes。您的应用可以在用户输入内容时发送查询，从而即时进行地点和查询预测。

例如，您可以使用包含用户输入部分内容（“Sicilian piz”）的字符串作为输入来调用自动补全功能，并将搜索区域限制为加利福尼亚州旧金山。然后，响应中会包含与搜索字符串和搜索区域匹配的地点预测结果列表，例如名为“Sicilian Pizza Kitchen”的餐厅。返回的地点预测结果旨在向用户显示，以帮助他们选择所需的地点。您可以发出地点详情（新）请求，详细了解返回的任何地点预测结果。

您可以通过以下两种主要方式将“自动补全（新）”功能集成到您的应用中：

添加地点自动补全 widget：通过 PlaceAutocomplete 类提供可供使用的搜索自动补全体验，该类会在用户输入内容时显示预测结果。
以编程方式获取地点预测：直接调用 API 以检索预测结果并将其显示在自定义界面中。

为了更轻松地提供一致的地点自动补全体验，您可以向应用中添加地点自动补全 widget。该 widget 提供专用的全屏界面，用于处理用户输入并向用户显示地点预测结果，同时将 AutocompletePrediction 对象返回给应用。然后，您可以发出地点详情（新）请求，以获取有关任何地点预测结果的更多信息。

与以程序化方式获取地点预测结果时一样，地点自动补全 widget 允许您使用会话令牌将自动补全请求分组到会话中，以便进行结算。您可以在为微件创建 intent 时通过调用 setAutocompleteSessionToken() 传递会话令牌。如果您未提供会话令牌，该 widget 会为您创建一个，您可以通过调用 getSessionTokenFromIntent() 来访问该令牌。如需详细了解如何使用会话令牌，请参阅会话令牌简介。

如需向应用添加地点自动补全微件，请执行以下操作：

（可选）定义会话令牌。如果您未提供会话令牌，该 widget 会为您创建一个。
使用所需的参数和会话令牌定义 autocompleteIntent。
为 StartActivityForResult 定义 ActivityResultLauncher。此启动器将处理从自动补全 activity 返回的结果。
在 ActivityResultLauncher 的回调中处理结果。这涉及提取 AutocompletePrediction 和 AutocompleteSessionToken（如果您未提供自己的 AutocompletePrediction 和 AutocompleteSessionToken），处理错误，以及视需要发出 fetchPlace() 请求以获取与地点相关的更多详细信息。
使用 placeAutocompleteActivityResultLauncher 启动 intent

以下示例演示了如何同时使用 Kotlin 和 Java 添加地点自动补全微件：

Kotlin

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

Java

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

以编程方式获取地点预测

您的应用可以通过调用 PlacesClient.findAutocompletePredictions() 并传递 FindAutocompletePredictionsRequest 对象，从 autocomplete API 获取预测的地点名称和/或地址列表。以下示例展示了对 PlacesClient.findAutocompletePredictions() 的完整调用。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

注意：如需详细了解如何初始化 PlacesClient，请参阅初始化 Places API 客户端。