API Maps trên Wear OS

Bản đồ trên thiết bị đeo

Bằng cách sử dụng SDK Maps dành cho Android, bạn có thể tạo một ứng dụng mặc định dựa trên bản đồ chạy trực tiếp trên các thiết bị Wear OS by Google. Người dùng ứng dụng của bạn có thể xem vị trí của họ trên bản đồ chỉ bằng cách nhìn lướt qua cổ tay. Ví dụ: Người dùng có thể vẽ sơ đồ vị trí của họ trên một tuyến đường, sau đó phóng to để xem thông tin chi tiết hoặc nhấn vào một điểm đánh dấu để xem cửa sổ thông tin do ứng dụng của bạn cung cấp.

Trang này mô tả chức năng API có sẵn trên thiết bị Wear và giúp bạn bắt đầu xây dựng ứng dụng.

Bắt đầu trên Wear OS

Về cơ bản, việc tạo một ứng dụng dành cho thiết bị đeo bằng SDK Maps dành cho Android cũng giống như việc xây dựng một ứng dụng Google Maps cho bất kỳ thiết bị Android nào khác. Điểm khác biệt nằm ở thiết kế của bạn đối với kiểu dáng nhỏ hơn của thiết bị đeo, nhằm tối ưu hoá khả năng hữu dụng và hiệu suất của ứng dụng.

Android Studio là công cụ được đề xuất cho việc phát triển Wear OS, vì công cụ này cung cấp tính năng thiết lập dự án, đưa thư viện vào và đóng gói tiện lợi.

Để được trợ giúp chung về việc thiết kế ứng dụng cho thiết bị đeo, hãy tham khảo Nguyên tắc thiết kế cho Wear OS. Để được trợ giúp tạo ứng dụng đầu tiên dành cho thiết bị đeo, hãy xem hướng dẫn về cách tạo ứng dụng dành cho thiết bị đeo.

Xây dựng ứng dụng bản đồ đầu tiên trên Wear OS

Hướng dẫn nhanh này giả định rằng bạn đã quen thuộc với SDK Maps dành cho Android, rằng bạn đã làm theo hướng dẫn của Wear OS để tạo một mô-đun thiết bị đeo trong ứng dụng của mình và giờ đây, bạn muốn thêm bản đồ vào mô-đun thiết bị đeo.

Thêm các phần phụ thuộc cho mô-đun Wear

Đảm bảo rằng các phần phụ thuộc sau có trong tệp build.gradle của mô-đun Wear OS của ứng dụng:

dependencies {
    // ...
    compileOnly 'com.google.android.wearable:wearable:2.9.0'
    implementation 'com.google.android.support:wearable:2.9.0'
    implementation 'com.google.android.gms:play-services-maps:18.0.2'

    // This dependency is necessary for ambient mode
    implementation 'androidx.wear:wear:1.2.0'
}

Để biết thêm thông tin về các phần phụ thuộc, hãy xem hướng dẫn Thêm mô-đun Wear OS vào dự án hiện tại của bạn.

Triển khai cử chỉ vuốt để đóng và đặt màu nền ban đầu

Bạn nên dùng SwipeDismissFrameLayout để hiển thị bản đồ trên thiết bị đeo. Sử dụng lớp SwipeDismissFrameLayout, bạn có thể triển khai cử chỉ vuốt để di chuyển để người dùng có thể thoát khỏi ứng dụng bằng cách vuốt từ mép ngoài cùng bên trái của màn hình.

Để đặt màu nền ban đầu tuỳ chỉnh, hãy sử dụng thuộc tính XML map:backgroundColor để xác định màu cần hiển thị cho đến khi ô bản đồ thực tế tải.

Thêm các phần tử SwipeDismissFrameLayoutbackgroundColor vào định nghĩa bố cục làm vùng chứa của SupportMapFragment:

  <androidx.wear.widget.SwipeDismissFrameLayout
      android:id="@+id/map_container"
      android:layout_width="match_parent"
      android:layout_height="match_parent">
    <fragment
        android:id="@+id/map"
        android:name="com.google.android.gms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        map:backgroundColor="#fff0b2dd" />
  </androidx.wear.widget.SwipeDismissFrameLayout>

Khi lấy đối tượng SwipeDismissFrameLayout trong hoạt động, hãy thêm lệnh gọi lại và đặt hành vi của lệnh gọi lại để thực hiện thao tác đóng cần thiết như bên dưới:

Java


public class MainActivity extends AppCompatActivity implements OnMapReadyCallback,
    AmbientModeSupport.AmbientCallbackProvider {


    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(MainActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        final SwipeDismissFrameLayout mapFrameLayout = (SwipeDismissFrameLayout) findViewById(
            R.id.map_container);
        mapFrameLayout.addCallback(new SwipeDismissFrameLayout.Callback() {
            @Override
            public void onDismissed(SwipeDismissFrameLayout layout) {
                onBackPressed();
            }
        });

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    // ...
}

      

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback,
                     AmbientModeSupport.AmbientCallbackProvider {


    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(MainActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Retrieve the containers for the root of the layout and the map. Margins will need to be
        // set on them to account for the system window insets.
        val mapFrameLayout = findViewById<SwipeDismissFrameLayout>(R.id.map_container)
        mapFrameLayout.addCallback(object : SwipeDismissFrameLayout.Callback() {
            override fun onDismissed(layout: SwipeDismissFrameLayout) {
                onBackPressed()
            }
        })

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    // ...
}

      

Thêm bản đồ

Sử dụng phương thức gọi lại onMapReady(GoogleMap) như bình thường để xử lý đối tượng GoogleMap. Lệnh gọi lại được kích hoạt khi bản đồ đã sẵn sàng để được sử dụng. Trong phương thức gọi lại, bạn có thể thêm điểm đánh dấu hoặc nhiều đường vào bản đồ, thêm trình nghe hoặc di chuyển máy ảnh. Ví dụ dưới đây sẽ thêm một điểm đánh dấu gần Nhà hát Opera Sydney:

Java


private static final LatLng SYDNEY = new LatLng(-33.85704, 151.21522);

@Override
public void onMapReady(@NonNull GoogleMap googleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(new MarkerOptions().position(SYDNEY)
        .title("Sydney Opera House"));

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, 10));
}

      

Kotlin


private val sydney = LatLng(-33.85704, 151.21522)

override fun onMapReady(googleMap: GoogleMap) {
    // Add a marker with a title that is shown in its info window.
    googleMap.addMarker(
        MarkerOptions().position(sydney)
            .title("Sydney Opera House")
    )

    // Move the camera to show the marker.
    googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, 10f))
}

      

Bật chế độ môi trường xung quanh

SDK Maps dành cho Android hỗ trợ chế độ môi trường xung quanh cho ứng dụng trên thiết bị đeo. Các ứng dụng hỗ trợ chế độ môi trường xung quanh đôi khi được gọi là ứng dụng luôn bật. Chế độ môi trường xung quanh được kích hoạt khi người dùng không còn sử dụng ứng dụng nữa và cho phép ứng dụng duy trì hiển thị trên thiết bị đeo.

SDK bản đồ dành cho Android cung cấp tính năng kết xuất đơn giản, có màu sắc thấp của bản đồ để sử dụng trong chế độ môi trường xung quanh và kiểu bản đồ sẽ tự động điều chỉnh khi thiết bị hoán đổi từ chế độ tương tác sang chế độ môi trường xung quanh. Tất cả các điểm đánh dấu, đối tượng và thành phần điều khiển trên giao diện người dùng sẽ biến mất ở chế độ môi trường xung quanh. Điều này làm giảm mức tiêu thụ điện năng của ứng dụng và đảm bảo giao diện nhất quán với các ứng dụng xung quanh khác, chẳng hạn như mặt đồng hồ.

Thực hiện các bước sau để đảm bảo ứng dụng của bạn sử dụng chế độ môi trường xung quanh của bản đồ:

  1. Cập nhật SDK Android của bạn để bao gồm nền tảng Android 6.0 (API 23) trở lên. Nền tảng này cung cấp các API cho phép các hoạt động chuyển sang chế độ môi trường xung quanh. Để biết thông tin về cách cập nhật SDK, hãy xem tài liệu Android về cách thêm gói SDK.
  2. Đảm bảo dự án của bạn nhắm đến Android 6.0 trở lên, bằng cách đặt targetSdkVersion thành 23 trở lên trong tệp kê khai ứng dụng.
  3. Thêm các phần phụ thuộc có thể đeo vào tệp build.gradle của ứng dụng. Xem mẫu trên trang này.
  4. Thêm mục nhập thư viện chia sẻ thiết bị đeo vào tệp kê khai ứng dụng cho thiết bị đeo, như mô tả trong lớp đào tạo về Android về duy trì ứng dụng của bạn hiển thị.
  5. Thêm quyền WAKE_LOCK vào tệp kê khai ứng dụng cầm tay và thiết bị đeo, như mô tả trong lớp đào tạo Android về giữ cho ứng dụng hiển thị.
  6. Trong phương thức onCreate() của hoạt động, hãy gọi phương thức AmbientModeSupport.attach(). Điều này cho hệ điều hành biết ứng dụng luôn bật, để khi tắt nguồn, thiết bị sẽ chuyển sang chế độ môi trường xung quanh thay vì quay lại mặt đồng hồ.
  7. Triển khai giao diện AmbientModeSupport.AmbientCallbackProvider trong Hoạt động để nó có thể nhận được các thay đổi về trạng thái của chế độ môi trường xung quanh.
  8. Thiết lập bản đồ của bạn để hỗ trợ chế độ môi trường xung quanh. Bạn có thể thực hiện việc này bằng cách đặt thuộc tính map:ambientEnabled="true" trong tệp bố cục XML của hoạt động hoặc thực hiện việc đó theo phương thức lập trình bằng cách đặt GoogleMapOptions.ambientEnabled(true). Chế độ cài đặt này thông báo cho API biết rằng ứng dụng phải tải trước các ô bản đồ cần thiết để sử dụng ở chế độ môi trường xung quanh.
  9. Khi hoạt động chuyển sang chế độ môi trường xung quanh, hệ thống sẽ gọi phương thức onEnterAmbient() trong AmbientCallback mà bạn cung cấp. Ghi đè onEnterAmbient() rồi gọi SupportMapFragment.onEnterAmbient(ambientDetails) hoặc MapView.onEnterAmbient(ambientDetails). API hoán đổi cho hoạt động kết xuất không tương tác và có màu sắc thấp của bản đồ.
  10. Tương tự, trong onExitAmbient(), hãy gọi SupportMapFragment.onExitAmbient() hoặc MapView.onExitAmbient(). API sẽ hoán đổi với quá trình kết xuất thông thường của bản đồ.

Mã mẫu sau đây bật chế độ môi trường xung quanh trong hoạt động:

Java


public class AmbientActivity extends AppCompatActivity implements
    AmbientModeSupport.AmbientCallbackProvider {

    private SupportMapFragment mapFragment;

    public void onCreate(Bundle savedState) {
        super.onCreate(savedState);

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main);

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        AmbientModeSupport.AmbientController controller = AmbientModeSupport.attach(this);
        Log.d(AmbientActivity.class.getSimpleName(), "Is ambient enabled: " + controller.isAmbient());

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = (SupportMapFragment) getSupportFragmentManager()
            .findFragmentById(R.id.map);
    }

    @Override
    public AmbientCallback getAmbientCallback() {
        return new AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            @Override
            public void onEnterAmbient(Bundle ambientDetails) {
                super.onEnterAmbient(ambientDetails);
                mapFragment.onEnterAmbient(ambientDetails);
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            @Override
            public void onExitAmbient() {
                super.onExitAmbient();
                mapFragment.onExitAmbient();
            }
        };
    }
}

      

Kotlin


class AmbientActivity : AppCompatActivity(), AmbientModeSupport.AmbientCallbackProvider {

    private lateinit var mapFragment: SupportMapFragment

    public override fun onCreate(savedState: Bundle?) {
        super.onCreate(savedState)

        // Set the layout. It only contains a SupportMapFragment and a DismissOverlay.
        setContentView(R.layout.activity_main)

        // Enable ambient support, so the map remains visible in simplified, low-color display
        // when the user is no longer actively using the app but the app is still visible on the
        // watch face.
        val controller = AmbientModeSupport.attach(this)
        Log.d(AmbientActivity::class.java.simpleName, "Is ambient enabled: " + controller.isAmbient)

        // Obtain the MapFragment and set the async listener to be notified when the map is ready.
        mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
    }

    override fun getAmbientCallback(): AmbientModeSupport.AmbientCallback {
        return object : AmbientModeSupport.AmbientCallback() {
            /**
             * Starts ambient mode on the map.
             * The API swaps to a non-interactive and low-color rendering of the map when the user is no
             * longer actively using the app.
             */
            override fun onEnterAmbient(ambientDetails: Bundle) {
                super.onEnterAmbient(ambientDetails)
                mapFragment.onEnterAmbient(ambientDetails)
            }

            /**
             * Exits ambient mode on the map.
             * The API swaps to the normal rendering of the map when the user starts actively using the app.
             */
            override fun onExitAmbient() {
                super.onExitAmbient()
                mapFragment.onExitAmbient()
            }
        }
    }
}

      

Bạn có thể cập nhật màn hình trong khi ứng dụng đang ở chế độ môi trường xung quanh. Để biết thêm thông tin chi tiết về cách cập nhật nội dung và về chế độ môi trường xung quanh nói chung, hãy xem lớp đào tạo của Android về cách giữ cho ứng dụng của bạn luôn hiển thị.

Sử dụng Chế độ xem phố trên Wear OS

Chế độ xem phố được hỗ trợ đầy đủ trên các thiết bị đeo.

Để cho phép người dùng thoát khỏi ứng dụng khi xem ảnh toàn cảnh của Chế độ xem phố, hãy sử dụng giao diện StreetViewToàn cảnh.OnStreetViewoverviewLongClickListener để thực hiện cử chỉ nhấp và giữ. Khi người dùng nhấp và giữ một vị trí nào đó trên hình ảnh Chế độ xem phố, bạn sẽ nhận được một sự kiện onStreetViewPanoramaLongClick(StreetViewPanoramaOrientation). Gọi DismissOverlayView.show() để hiện nút thoát.

Mã mẫu

Một ứng dụng mẫu có sẵn trên GitHub, bạn có thể dùng ứng dụng này làm điểm xuất phát cho ứng dụng. Mẫu này cho bạn biết cách thiết lập bản đồ Google cơ bản trên Wear OS.

Chức năng được hỗ trợ trong API Maps trên Wear OS

Phần này nêu ra những điểm khác biệt về chức năng được hỗ trợ cho bản đồ trên thiết bị đeo khi so sánh với thiết bị cầm tay (điện thoại và máy tính bảng). Tất cả các tính năng API không được đề cập bên dưới sẽ hoạt động như được ghi lại cho API đầy đủ.

Chức năng
Chế độ tương tác và chế độ thu gọn hoàn toàn

Bạn có thể sử dụng SDK Maps dành cho Android ở chế độ tương tác hoàn toàn hoặc ở chế độ thu gọn. Cân nhắc chế độ thu gọn nếu bạn muốn tối ưu hóa hiệu suất trên thiết bị đeo và ứng dụng của bạn không cần hỗ trợ tương tác như cử chỉ hoặc kéo và thu phóng bản đồ.

Ở chế độ thu gọn, ý định khởi động ứng dụng dành cho thiết bị di động của Google Maps khi người dùng nhấn vào bản đồ đó sẽ bị tắt và không thể bật trên thiết bị đeo.

Để xem danh sách đầy đủ sự khác biệt giữa chế độ thu gọn và chế độ tương tác đầy đủ, hãy xem tài liệu chế độ thu gọn.

Thanh công cụ của bản đồ Thanh công cụ bản đồ bị tắt và không thể bật trên thiết bị đeo.
Điều khiển giao diện người dùng Theo mặc định, các nút điều khiển giao diện người dùng sẽ bị tắt trên các thiết bị đeo. Bao gồm chế độ thu phóng, la bàn và các chế độ kiểm soát vị trí của tôi. Bạn có thể bật các lớp này bằng cách sử dụng lớp UiSettings như bình thường.
Cử chỉ Cử chỉ chạm một lần hoạt động như mong đợi. Ví dụ: chạm và kéo để xoay bản đồ, nhấn đúp để phóng to và nhấn bằng 2 ngón tay để thu nhỏ. Chức năng hỗ trợ khác nhau cho các cử chỉ đa điểm chạm tùy thuộc vào thiết bị của người dùng. Ví dụ về các cử chỉ nhiều điểm nhấn bao gồm tính năng nhấn bằng 2 ngón tay để nghiêng bản đồ, chụm để thu phóng và xoay bằng 2 ngón tay.
Bản đồ và toà nhà trong nhà Theo mặc định, bản đồ trong nhà sẽ bị tắt trên thiết bị đeo. Bạn có thể bật các tính năng này bằng cách gọi GoogleMap.setIndoorEnabled(true). Nếu bạn bật bản đồ trong nhà, thì bản đồ này sẽ hiển thị cấp tầng mặc định. Thành phần giao diện người dùng bộ chọn cấp không được hỗ trợ trên các thiết bị đeo.
Lớp phủ xếp kề Lớp phủ dạng ô không được hỗ trợ trên thiết bị đeo.

Các phương pháp hay nhất để phát triển bằng API Maps trên Wear OS

Cách cung cấp trải nghiệm người dùng tốt nhất trong ứng dụng của bạn:

  • Bản đồ phải chiếm một tỷ lệ lớn màn hình. Việc này là cần thiết để tối ưu hoá khả năng hữu dụng của bản đồ trên kiểu dáng nhỏ của thiết bị đeo.
  • Khi thiết kế trải nghiệm người dùng của ứng dụng, hãy tính đến thực tế rằng thiết bị đeo có pin yếu. Việc duy trì hoạt động của màn hình và hiển thị bản đồ sẽ ảnh hưởng đến hiệu suất pin.