此页面由 Cloud Translation API 翻译。

自动补全（新）

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

欧洲经济区 (EEA) 开发者

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

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

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

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

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

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

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

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

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

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 对象，从自动补全 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 客户端。