รูปทรง

เลือกแพลตฟอร์ม: Android iOS JavaScript

แผนที่ที่มีเส้นประกอบสีแดงทึบ

Google Maps API สำหรับ Android มีวิธีง่ายๆ ในการเพิ่มรูปร่างลงในแผนที่เพื่อปรับแต่งให้เหมาะกับแอปพลิเคชันของคุณ

  • Polyline คือชุดของส่วนของเส้นตรงที่เชื่อมต่อกันซึ่งสามารถสร้างเป็นรูปร่างใดก็ได้ตามต้องการ และใช้เพื่อทำเครื่องหมายเส้นทางและเส้นทางบนแผนที่ได้
  • Polygon คือรูปร่างปิดที่ใช้ทำเครื่องหมายพื้นที่บนแผนที่ได้
  • Circle คือการฉายภาพวงกลมที่แม่นยำทางภูมิศาสตร์บนพื้นผิวโลกที่วาดบนแผนที่

คุณสามารถปรับแต่งรูปร่างทั้งหมดเหล่านี้ได้โดยการเปลี่ยนคุณสมบัติหลายอย่าง

ตัวอย่างโค้ด

บทแนะนำเกี่ยวกับการเพิ่มรูปหลายเหลี่ยมและเส้นประกอบเพื่อแสดงพื้นที่และเส้นทางมีโค้ดทั้งหมดสำหรับแอป Android แบบง่าย

นอกจากนี้ ที่เก็บ ApiDemos ใน GitHub ยังมีตัวอย่างที่สาธิตการใช้รูปร่างและฟีเจอร์ของรูปร่างด้วย ดังนี้

  • CircleDemoActivity (Java / Kotlin): วงกลม
  • PolygonDemoActivity (Java / Kotlin): รูปหลายเหลี่ยม
  • PolylineDemoActivity (Java / Kotlin): เส้นประกอบ

เส้นประกอบ

คลาส Polyline กำหนดชุดของส่วนของเส้นที่เชื่อมต่อกันบนแผนที่ ออบเจ็กต์ Polyline ประกอบด้วยชุดตำแหน่ง LatLng และสร้างชุดของส่วนของเส้นตรงที่เชื่อมต่อตำแหน่งเหล่านั้นตามลำดับที่เรียงไว้

วิดีโอนี้จะให้แนวคิดเกี่ยวกับวิธีช่วยให้ผู้ใช้ไปยังจุดหมายที่ต้องการโดยใช้เส้นประกอบเพื่อวาดเส้นทางบนแผนที่

หากต้องการสร้างเส้นประกอบ ให้สร้างออบเจ็กต์ PolylineOptions ก่อน แล้วจึงเพิ่มจุดลงในออบเจ็กต์ จุดแสดงถึงจุดบนพื้นผิวโลก และแสดงเป็นออบเจ็กต์ LatLng ระบบจะวาดส่วนของเส้นตรงระหว่างจุดต่างๆ ตามลำดับที่คุณเพิ่มจุดเหล่านั้นลงในออบเจ็กต์ PolylineOptions

หากต้องการเพิ่มจุดลงในออบเจ็กต์ PolylineOptions ให้เรียกใช้ PolylineOptions.add() โปรดทราบว่าเมธอดนี้ใช้พารามิเตอร์จำนวนตัวแปรเพื่อให้คุณเพิ่มจุดหลายจุดพร้อมกันได้ (คุณยังเรียกใช้ PolylineOptions.addAll(Iterable<LatLng>) ได้ด้วยหากจุดอยู่ในรายการแล้ว)

จากนั้นคุณสามารถเพิ่มเส้นประกอบลงในแผนที่ได้โดยเรียกใช้ GoogleMap.addPolyline(PolylineOptions) เมธอดจะแสดงผลออบเจ็กต์ Polyline ซึ่งคุณสามารถแก้ไขเส้นประกอบได้ในภายหลัง

ข้อมูลโค้ดต่อไปนี้แสดงวิธีเพิ่มสี่เหลี่ยมผืนผ้าลงในแผนที่

Kotlin

// Instantiates a new Polyline object and adds points to define a rectangle
val polylineOptions = PolylineOptions()
    .add(LatLng(37.35, -122.0))
    .add(LatLng(37.45, -122.0)) // North of the previous point, but at the same longitude
    .add(LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
    .add(LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
    .add(LatLng(37.35, -122.0)) // Closes the polyline.

// Get back the mutable Polyline
val polyline = map.addPolyline(polylineOptions)

Java

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions polylineOptions =
        new PolylineOptions()
                .add(new LatLng(37.35, -122.0))
                .add(
                        new LatLng(
                                37.45,
                                -122.0)) // North of the previous point, but at the same
                // longitude
                .add(new LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
                .add(new LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
                .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = map.addPolyline(polylineOptions);

สี่เหลี่ยมผืนผ้าจะปรากฏบนแผนที่ดังที่แสดงด้านล่าง

แผนที่ที่มีเส้นประกอบสี่เหลี่ยมผืนผ้า

หากต้องการเปลี่ยนรูปร่างของเส้นประกอบหลังจากเพิ่มแล้ว คุณสามารถเรียกใช้ Polyline.setPoints() และระบุรายการจุดใหม่สำหรับเส้นประกอบได้

คุณปรับแต่งลักษณะที่ปรากฏของเส้นประกอบได้ทั้งก่อนเพิ่มลงในแผนที่และหลังจากเพิ่มลงในแผนที่แล้ว ดูรายละเอียดเพิ่มเติมได้ที่ส่วนการปรับแต่งรูปลักษณ์ด้านล่าง

การปรับแต่งเส้นประกอบ

คุณปรับแต่งลักษณะที่ปรากฏของเส้นประกอบได้หลายวิธี ดังนี้

  • เส้นประกอบหลากสีตั้งค่าส่วนของเส้นประกอบเป็นสีต่างๆ
  • เส้นประกอบแบบไล่ระดับสีจะลงสีเส้นประกอบโดยใช้การไล่ระดับสี 2 สี
  • เส้นประกอบแบบประทับจะจัดสไตล์เส้นประกอบโดยใช้บิตแมปซ้ำๆ

หากต้องการใช้การปรับแต่งเส้นประกอบ ให้ใช้ Maps SDK สำหรับ Android เวอร์ชัน 18.1.0 ขึ้นไป และใช้โปรแกรมแสดงผล Maps SDK สำหรับ Android เวอร์ชันล่าสุด

การสร้างเส้นประกอบหลายสี

แผนที่ที่มีเส้นประกอบหลากสี

คุณสามารถใช้ช่วงเพื่อลงสีแต่ละส่วนของเส้นประกอบได้โดยสร้างออบเจ็กต์ StyleSpan และเพิ่มลงใน PolylineOptions โดยใช้เมธอด addSpan() หรือ addSpans() โดยค่าเริ่มต้น แต่ละรายการในอาร์เรย์จะกำหนดสีของส่วนของเส้นที่เกี่ยวข้อง ตัวอย่างต่อไปนี้แสดงการตั้งค่าสีของส่วนเพื่อสร้างเส้นประกอบที่มีส่วนสีแดงและสีเขียว

Kotlin

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(StyleSpan(Color.RED))
        .addSpan(StyleSpan(Color.GREEN)),
)

Java

Polyline line =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(47.6677146, -122.3470447),
                                new LatLng(47.6442757, -122.2814693))
                        .addSpan(new StyleSpan(Color.RED))
                        .addSpan(new StyleSpan(Color.GREEN)));

การสร้างเส้นประกอบแบบไล่ระดับสี

แผนที่ที่มีเส้นประกอบแบบไล่ระดับสี

คุณกำหนดการไล่ระดับสีได้โดยระบุจำนวนเต็มแบบ 32 บิตของสีอัลฟา-แดง-เขียว-น้ำเงิน (ARGB) 2 จำนวน เพื่อระบุสีเริ่มต้นและสีสิ้นสุดของเส้นขอบ ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ PolylineOptions.addSpan() ตัวอย่างต่อไปนี้แสดงการสร้างเส้นประกอบแบบไล่ระดับสีแดงเป็นสีเหลืองจากสวนสัตว์วูดแลนด์พาร์คไปยังเคิร์กแลนด์ รัฐวอชิงตัน

Kotlin

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(
            StyleSpan(
                StrokeStyle.gradientBuilder(
                    Color.RED,
                    Color.YELLOW,
                ).build(),
            ),
        ),
)

Java

Polyline line =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(47.6677146, -122.3470447),
                                new LatLng(47.6442757, -122.2814693))
                        .addSpan(
                                new StyleSpan(
                                        StrokeStyle.gradientBuilder(Color.RED, Color.YELLOW)
                                                .build())));

การสร้างเส้นประกอบที่มีการประทับตรา

แผนที่ที่มีเส้นประกอบแบบประทับตรา

คุณสามารถตั้งค่าลักษณะของเส้นประกอบเป็นพื้นผิวบิตแมปที่เกิดซ้ำได้ โดยสร้าง StampStyle ของ TextureStyle แล้วตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ PolylineOptions.addSpan() ดังที่แสดงที่นี่

Kotlin

val stampStyle =
    TextureStyle.newBuilder(BitmapDescriptorFactory.fromResource(R.drawable.walking_dot)).build()
val span = StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build())
map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(span),
)

Java

StampStyle stampStyle =
        TextureStyle.newBuilder(
                        BitmapDescriptorFactory.fromResource(R.drawable.walking_dot))
                .build();
StyleSpan span =
        new StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build());
map.addPolyline(
        new PolylineOptions()
                .add(
                        new LatLng(47.6677146, -122.3470447),
                        new LatLng(47.6442757, -122.2814693))
                .addSpan(span));

เหตุการณ์เส้นประกอบ

โดยค่าเริ่มต้น เส้นประกอบจะคลิกไม่ได้ คุณเปิดและปิดใช้ความสามารถในการคลิกได้โดยเรียกใช้ Polyline.setClickable(boolean)

ใช้ OnPolylineClickListener เพื่อฟังกิจกรรมการคลิกในเส้นประกอบที่คลิกได้ หากต้องการตั้งค่า Listener นี้ในแผนที่ ให้เรียกใช้ GoogleMap.setOnPolylineClickListener(OnPolylineClickListener) เมื่อผู้ใช้คลิกเส้นประกอบ คุณจะได้รับ Callback onPolylineClick(Polyline)

รูปหลายเหลี่ยม

ออบเจ็กต์ Polygon คล้ายกับออบเจ็กต์ Polyline ตรงที่ประกอบด้วยชุดพิกัดตามลำดับที่เรียงไว้ อย่างไรก็ตาม แทนที่จะเป็นแบบปลายเปิด รูปหลายเหลี่ยมได้รับการออกแบบมาเพื่อกำหนดขอบเขตภายในลูปปิดที่มีการเติมสีภายใน

คุณสามารถเพิ่ม Polygon ลงในแผนที่ได้ด้วยวิธีเดียวกับการเพิ่ม Polyline ก่อนอื่น ให้สร้างออบเจ็กต์ PolygonOptions และเพิ่มจุดลงไป จุดเหล่านี้จะสร้างเป็นโครงร่างของรูปหลายเหลี่ยม จากนั้นเพิ่มรูปหลายเหลี่ยมลงในแผนที่โดยเรียกใช้ GoogleMap.addPolygon(PolygonOptions) ซึ่งจะแสดงผลออบเจ็กต์ Polygon

ข้อมูลโค้ดต่อไปนี้จะเพิ่มสี่เหลี่ยมผืนผ้าลงในแผนที่

Kotlin

// Instantiates a new Polygon object and adds points to define a rectangle
val rectOptions = PolygonOptions()
    .add(
        LatLng(37.35, -122.0),
        LatLng(37.45, -122.0),
        LatLng(37.45, -122.2),
        LatLng(37.35, -122.2),
        LatLng(37.35, -122.0),
    )

// Get back the mutable Polygon
val polygon = map.addPolygon(rectOptions)

Java

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions polygonOptions =
        new PolygonOptions()
                .add(
                        new LatLng(37.35, -122.0),
                        new LatLng(37.45, -122.0),
                        new LatLng(37.45, -122.2),
                        new LatLng(37.35, -122.2),
                        new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = map.addPolygon(polygonOptions);

หากต้องการเปลี่ยนรูปร่างของรูปหลายเหลี่ยมหลังจากเพิ่มแล้ว คุณสามารถเรียกใช้ Polygon.setPoints() และระบุรายการจุดใหม่สำหรับเส้นขอบของรูปหลายเหลี่ยม

คุณสามารถปรับแต่งลักษณะที่ปรากฏของรูปหลายเหลี่ยมได้ทั้งก่อนเพิ่มลงในแผนที่และหลังจากเพิ่มลงในแผนที่แล้ว ดูรายละเอียดเพิ่มเติมได้ที่ส่วนการปรับแต่งรูปลักษณ์ด้านล่าง

การเติมรูปหลายเหลี่ยมอัตโนมัติ

Polygon ในตัวอย่างด้านบนประกอบด้วยพิกัด 5 จุด แต่โปรดสังเกตว่าพิกัดแรกและพิกัดสุดท้ายเป็นตำแหน่งเดียวกัน ซึ่งกำหนดลูป อย่างไรก็ตาม ในทางปฏิบัติ เนื่องจากรูปหลายเหลี่ยมกำหนดพื้นที่ปิด คุณจึงไม่จำเป็นต้องกำหนดพิกัดสุดท้ายนี้ หากพิกัดสุดท้ายแตกต่างจากพิกัดแรก API จะ "ปิด" รูปหลายเหลี่ยมโดยอัตโนมัติด้วยการเพิ่มพิกัดแรกที่ส่วนท้ายของลำดับพิกัด

รูปหลายเหลี่ยม 2 รูปด้านล่างเทียบเท่ากัน และการเรียกใช้ polygon.getPoints() สำหรับแต่ละรูปจะแสดงผลทั้ง 4 จุด

Kotlin

val polygon1 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(0.0, 0.0),
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE),
)
val polygon2 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE),
)

Java

Polygon polygon1 =
        map.addPolygon(
                new PolygonOptions()
                        .add(
                                new LatLng(0, 0),
                                new LatLng(0, 5),
                                new LatLng(3, 5),
                                new LatLng(0, 0))
                        .strokeColor(Color.RED)
                        .fillColor(Color.BLUE));

Polygon polygon2 =
        map.addPolygon(
                new PolygonOptions()
                        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
                        .strokeColor(Color.RED)
                        .fillColor(Color.BLUE));

สร้างรูปหลายเหลี่ยมแบบกลวง

คุณสามารถรวมเส้นทางหลายเส้นทางไว้ในออบเจ็กต์ Polygon เดียวเพื่อสร้างรูปร่างที่ซับซ้อน เช่น วงแหวนที่เติมสี หรือ "โดนัท" (ซึ่งพื้นที่รูปหลายเหลี่ยมปรากฏภายในรูปหลายเหลี่ยมเป็น "เกาะ") รูปร่างที่ซับซ้อนมักประกอบด้วยเส้นทางที่เรียบง่ายหลายเส้นทาง

ต้องกำหนดเส้นทาง 2 เส้นทางในพื้นที่เดียวกัน พื้นที่ที่ใหญ่กว่าจาก 2 พื้นที่จะกำหนดพื้นที่เติม และเป็นรูปหลายเหลี่ยมแบบง่ายที่ไม่มีตัวเลือกเพิ่มเติม จากนั้นส่งเส้นทางที่ 2 ไปยังเมธอด addHole() เมื่อเส้นทางที่ 2 ซึ่งมีขนาดเล็กกว่าถูกล้อมรอบด้วยเส้นทางที่ใหญ่กว่าทั้งหมด จะปรากฏเป็นเหมือนว่าส่วนหนึ่งของรูปหลายเหลี่ยมถูกนำออกไป หากรูตัดกับโครงร่างของรูปหลายเหลี่ยม ระบบจะแสดงผลรูปหลายเหลี่ยมโดยไม่มีการเติมสี

ข้อมูลโค้ดด้านล่างจะสร้างสี่เหลี่ยมผืนผ้าเดียวที่มีรูสี่เหลี่ยมผืนผ้าขนาดเล็กกว่า

Kotlin

val hole = listOf(
    LatLng(1.0, 1.0),
    LatLng(1.0, 2.0),
    LatLng(2.0, 2.0),
    LatLng(2.0, 1.0),
    LatLng(1.0, 1.0),
)
val hollowPolygon = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(3.0, 0.0),
            LatLng(0.0, 0.0),
        )
        .addHole(hole)
        .fillColor(Color.BLUE),
)

Java

List<LatLng> hole =
        Arrays.asList(
                new LatLng(1, 1),
                new LatLng(1, 2),
                new LatLng(2, 2),
                new LatLng(2, 1),
                new LatLng(1, 1));
Polygon hollowPolygon =
        map.addPolygon(
                new PolygonOptions()
                        .add(
                                new LatLng(0, 0),
                                new LatLng(0, 5),
                                new LatLng(3, 5),
                                new LatLng(3, 0),
                                new LatLng(0, 0))
                        .addHole(hole)
                        .fillColor(Color.BLUE));

รูปหลายเหลี่ยมแบบกลวงจะปรากฏบนแผนที่ดังที่แสดงด้านล่าง

แผนที่ที่มีเส้นประกอบสี่เหลี่ยมผืนผ้ากลวง

เหตุการณ์รูปหลายเหลี่ยม

โดยค่าเริ่มต้น รูปหลายเหลี่ยมจะคลิกไม่ได้ คุณเปิดและปิดใช้ความสามารถในการคลิกได้โดยเรียกใช้ Polygon.setClickable(boolean)

ใช้ OnPolygonClickListener เพื่อฟังกิจกรรมการคลิกในรูปหลายเหลี่ยมที่คลิกได้ หากต้องการตั้งค่า Listener นี้ในแผนที่ ให้เรียกใช้ GoogleMap.setOnPolygonClickListener(OnPolygonClickListener) เมื่อผู้ใช้คลิกรูปหลายเหลี่ยม คุณจะได้รับ Callback onPolygonClick(Polygon)

วงกลม

แผนที่ที่มีวงกลม

นอกจากคลาส Polygon ทั่วไปแล้ว Maps API ยังมีคลาสเฉพาะสำหรับออบเจ็กต์ Circle เพื่อให้สร้างได้ง่ายขึ้น

หากต้องการสร้างวงกลม คุณต้องระบุพร็อพเพอร์ตี้ 2 รายการต่อไปนี้

  • center เป็นLatLng
  • radius ในหน่วยเมตร

จากนั้นระบบจะกำหนดวงกลมเป็นชุดของจุดทั้งหมดบนพื้นผิวโลกซึ่งอยู่ห่างจาก center ที่กำหนดเป็นระยะทาง radius เมตร เนื่องจากวิธีที่การฉายภาพแบบเมอร์เคเตอร์ที่ Maps API ใช้แสดงผลทรงกลมบนพื้นผิวเรียบ วงกลมนี้จะปรากฏเป็นวงกลมที่เกือบสมบูรณ์แบบบนแผนที่เมื่ออยู่ใกล้เส้นศูนย์สูตร และจะปรากฏเป็นวงกลมที่ไม่สมบูรณ์มากขึ้น (บนหน้าจอ) เมื่อวงกลมเคลื่อนออกจากเส้นศูนย์สูตร

หากต้องการเปลี่ยนรูปร่างของวงกลมหลังจากเพิ่มแล้ว คุณสามารถเรียกใช้ Circle.setRadius() หรือ Circle.setCenter() และระบุค่าใหม่ได้

คุณสามารถปรับแต่งลักษณะที่ปรากฏของวงกลมได้ทั้งก่อนเพิ่มลงในแผนที่และหลังจากเพิ่มลงในแผนที่แล้ว ดูรายละเอียดเพิ่มเติมได้ที่ส่วนการปรับแต่งรูปลักษณ์ด้านล่าง

ข้อมูลโค้ดต่อไปนี้จะเพิ่มวงกลมลงในแผนที่โดยการสร้างออบเจ็กต์ CircleOptions และเรียกใช้ GoogleMap.addCircle(CircleOptions)

Kotlin

// Instantiates a new CircleOptions object and defines the center and radius
val circleOptions = CircleOptions()
    .center(LatLng(37.4, -122.1))
    .radius(1000.0) // In meters

// Get back the mutable Circle
val circle = map.addCircle(circleOptions)

Java

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions =
        new CircleOptions().center(new LatLng(37.4, -122.1)).radius(1000); // In meters

// Get back the mutable Circle
Circle circle = map.addCircle(circleOptions);

กิจกรรมในแวดวง

โดยค่าเริ่มต้น วงกลมจะคลิกไม่ได้ คุณเปิดและปิดใช้ความสามารถในการคลิกได้โดยเรียกใช้ GoogleMap.addCircle() ด้วย CircleOptions.clickable(boolean) หรือเรียกใช้ Circle.setClickable(boolean)

ใช้ OnCircleClickListener เพื่อฟังกิจกรรมการคลิกในวงกลมที่คลิกได้ หากต้องการตั้งค่า Listener นี้ในแผนที่ ให้เรียกใช้ GoogleMap.setOnCircleClickListener(OnCircleClickListener)

เมื่อผู้ใช้คลิกวงกลม คุณจะได้รับ Callback onCircleClick(Circle) ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้

Kotlin

val circle = map.addCircle(
    CircleOptions()
        .center(LatLng(37.4, -122.1))
        .radius(1000.0)
        .strokeWidth(10f)
        .strokeColor(Color.GREEN)
        .fillColor(Color.argb(128, 255, 0, 0))
        .clickable(true),
)
map.setOnCircleClickListener {
    // Flip the r, g and b components of the circle's stroke color.
    val strokeColor = it.strokeColor xor 0x00ffffff
    it.strokeColor = strokeColor
}

Java

Circle circle =
        map.addCircle(
                new CircleOptions()
                        .center(new LatLng(37.4, -122.1))
                        .radius(1000)
                        .strokeWidth(10)
                        .strokeColor(Color.GREEN)
                        .fillColor(Color.argb(128, 255, 0, 0))
                        .clickable(true));

map.setOnCircleClickListener(
        new GoogleMap.OnCircleClickListener() {
            @Override
            public void onCircleClick(Circle circle) {
                // Flip the r, g and b components of the circle's stroke color.
                int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                circle.setStrokeColor(strokeColor);
            }
        });

การปรับแต่งลักษณะที่ปรากฏ

คุณสามารถเปลี่ยนลักษณะที่ปรากฏของรูปร่างได้ทั้งก่อนที่จะเพิ่มลงในแผนที่ (โดยระบุพร็อพเพอร์ตี้ที่ต้องการในออบเจ็กต์ตัวเลือก) หรือหลังจากที่เพิ่มลงในแผนที่แล้ว นอกจากนี้ยังมีการแสดง Getter สำหรับพร็อพเพอร์ตี้ทั้งหมดเพื่อให้คุณเข้าถึงสถานะปัจจุบันของรูปร่างได้อย่างง่ายดาย

ข้อมูลโค้ดต่อไปนี้จะเพิ่มเส้นประกอบสีน้ำเงินหนาที่มีส่วนทางภูมิศาสตร์จากเมลเบิร์นไปยังเพิร์ท ส่วนด้านล่างจะอธิบายพร็อพเพอร์ตี้เหล่านี้โดยละเอียด

Kotlin

val polyline = map.addPolyline(
    PolylineOptions()
        .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
        .width(25f)
        .color(Color.BLUE)
        .geodesic(true),
)

Java

Polyline polyline =
        map.addPolyline(
                new PolylineOptions()
                        .add(
                                new LatLng(-37.81319, 144.96298),
                                new LatLng(-31.95285, 115.85734))
                        .width(25)
                        .color(Color.BLUE)
                        .geodesic(true));

แผนที่จะปรากฏดังที่แสดงด้านล่าง

แผนที่ที่มีเส้นประกอบจากเมลเบิร์นไปยังเพิร์ท

หมายเหตุ: แม้ว่าคุณสมบัติส่วนใหญ่เหล่านี้จะใช้ได้กับรูปร่างที่อธิบายไว้ แต่คุณสมบัติบางอย่างอาจไม่เหมาะกับรูปร่างบางประเภท (เช่น เส้นประกอบจะไม่มีสีเติมเนื่องจากไม่มีพื้นที่ภายใน)

ใส่สีเส้นโครงร่าง

สีเส้นขอบเป็นจำนวนเต็มแบบ Alpha-Red-Green-Blue (ARGB) 32 บิตที่ระบุความทึบแสงและสีของเส้นขอบของรูปร่าง ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.strokeColor() (หรือ PolylineOptions.color() ในกรณีที่เป็นเส้นประกอบ) หากไม่ได้ระบุ สีเส้นเริ่มต้นจะเป็นสีดำ (Color.BLACK)

หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงสีเส้นได้โดยเรียกใช้ getStrokeColor() (หรือ getColor() สำหรับเส้นประกอบ) และเปลี่ยนสีได้โดยเรียกใช้ setStrokeColor() (setColor() for a polyline)

สีเติม

สีเติมใช้ได้กับรูปหลายเหลี่ยมและวงกลมเท่านั้น แต่จะไม่มีผลกับเส้นประกอบเนื่องจากไม่มีพื้นที่ภายในที่กำหนดไว้ สำหรับรูปหลายเหลี่ยม พื้นที่ภายในช่องว่างจะไม่ถือเป็นส่วนหนึ่งของรูปหลายเหลี่ยม และจะไม่ได้รับการลงสีหากมีการตั้งค่าสีเติมไว้

สีเติมคือจำนวนเต็ม Alpha-Red-Green-Blue (ARGB) แบบ 32 บิตที่ระบุความทึบแสงและสีภายในของรูปร่าง ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.fillColor() หากไม่ได้ระบุ สีเส้นขอบเริ่มต้นจะเป็นแบบโปร่งใส (Color.TRANSPARENT)

หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงสีเติมได้โดยเรียกใช้ getFillColor() และเปลี่ยนสีได้โดยเรียกใช้ setFillColor()

ความกว้างของเส้นโครงร่าง

ความกว้างของเส้นเป็นค่าแบบลอยในหน่วยพิกเซล (px) ความกว้างจะไม่ปรับขนาดเมื่อซูมแผนที่ (กล่าวคือ รูปร่างจะมีความกว้างของเส้นเท่ากันในทุกระดับการซูม) ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.strokeWidth() (หรือ PolylineOptions.width() สำหรับเส้นประกอบ) หากไม่ได้ระบุ ความกว้างของเส้นขีดเริ่มต้นคือ 10 พิกเซล

หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงความกว้างของเส้นได้โดยเรียกใช้ getStrokeWidth() (หรือ getWidth() สำหรับเส้นประกอบ) และเปลี่ยนแปลงได้โดยเรียกใช้ setStrokeWidth() (setWidth() for a polyline)

รูปแบบเส้น

รูปแบบเส้นขีดเริ่มต้นคือเส้นทึบสำหรับเส้นประกอบและสำหรับเส้นขอบของรูปหลายเหลี่ยมและวงกลม คุณสามารถระบุรูปแบบเส้นขีดที่กำหนดเองของออบเจ็กต์ PatternItem โดยที่แต่ละรายการเป็นขีด จุด หรือช่องว่าง

ตัวอย่างต่อไปนี้จะตั้งค่ารูปแบบสำหรับเส้นประกอบเป็นลำดับซ้ำของจุด ตามด้วยช่องว่างความยาว 20 พิกเซล ขีดกลางความยาว 30 พิกเซล และช่องว่างอีก 20 พิกเซล

Kotlin

val pattern = listOf(
    Dot(),
    Gap(20F),
    Dash(30F),
    Gap(20F),
)
polyline?.pattern = pattern

Java

List<PatternItem> pattern =
        Arrays.asList(new Dot(), new Gap(20), new Dash(30), new Gap(20));
polyline.setPattern(pattern);

รูปแบบจะซ้ำไปตามเส้น โดยเริ่มจากรายการรูปแบบแรกที่จุดยอดแรกที่ระบุสำหรับรูปร่าง

ประเภทข้อต่อ

สำหรับเส้นประกอบและเส้นขอบของรูปหลายเหลี่ยม คุณสามารถระบุการตัดมุมหรือการลบมุม JointType เพื่อแทนที่ประเภทข้อต่อแบบเข้ามุมคงที่เริ่มต้นได้

ตัวอย่างต่อไปนี้ใช้ประเภทข้อต่อแบบกลมกับเส้นประกอบ

Kotlin

polyline?.jointType = JointType.ROUND

Java

polyline.setJointType(JointType.ROUND);

ประเภทข้อต่อจะส่งผลต่อการโค้งงอภายในเส้น หากเส้นมีรูปแบบเส้นที่รวมขีดกลาง ประเภทข้อต่อจะใช้เมื่อขีดกลางคร่อมข้อต่อด้วย ประเภทข้อต่อไม่มีผลต่อจุด เนื่องจากจุดจะเป็นวงกลมเสมอ

ปลายเส้น

คุณระบุรูปแบบ Cap สำหรับปลายแต่ละด้านของเส้นประกอบได้ ตัวเลือกคือแบบตัด (ค่าเริ่มต้น) แบบสี่เหลี่ยมจัตุรัส แบบกลม หรือบิตแมปที่กำหนดเอง ตั้งค่ารูปแบบใน PolylineOptions.startCap และ PolylineOptions.endCap หรือใช้เมธอด Getter และ Setter ที่เหมาะสม

ข้อมูลโค้ดต่อไปนี้ระบุเส้นปลายมนที่จุดเริ่มต้นของเส้นประกอบ

Kotlin

polyline?.startCap = RoundCap()

Java

polyline.setStartCap(new RoundCap());

ข้อมูลโค้ดต่อไปนี้ระบุบิตแมปที่กำหนดเองสำหรับส่วนปลาย

Kotlin

polyline?.endCap = CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16F)

Java

polyline.setEndCap(
        new CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16));

เมื่อใช้บิตแมปที่กำหนดเอง คุณควรระบุความกว้างของเส้นอ้างอิงเป็นพิกเซล API จะปรับขนาดบิตแมปตามความเหมาะสม ความกว้างของเส้นอ้างอิงคือความกว้างของเส้นที่คุณใช้เมื่อออกแบบรูปภาพบิตแมปสำหรับส่วนปลายที่ขนาดเดิมของรูปภาพ ความกว้างของเส้นอ้างอิงเริ่มต้นคือ 10 พิกเซล คำแนะนำ: หากต้องการกำหนดความกว้างของเส้นอ้างอิง ให้เปิดภาพบิตแมปที่ซูม 100% ในเครื่องมือแก้ไขรูปภาพ แล้ววาดความกว้างที่ต้องการของเส้นที่สัมพันธ์กับรูปภาพ

หากคุณใช้ BitmapDescriptorFactory.fromResource() เพื่อสร้างบิตแมป ให้ตรวจสอบว่าคุณใช้ทรัพยากรที่ไม่ขึ้นอยู่กับความหนาแน่น (nodpi)

ส่วน Geodesic

การตั้งค่าเส้นทางภูมิศาสตร์จะใช้ได้กับเส้นประกอบและรูปหลายเหลี่ยมเท่านั้น แต่จะใช้กับแวดวงไม่ได้เนื่องจากไม่ได้กำหนดให้เป็นคอลเล็กชันของกลุ่ม

การตั้งค่า Geodesic จะกำหนดวิธีวาดส่วนของเส้นตรงระหว่างจุดยอดที่ต่อเนื่องกันของเส้นประกอบ/รูปหลายเหลี่ยม ส่วนทางภูมิศาสตร์คือส่วนที่ตามเส้นทางที่สั้นที่สุดตามพื้นผิวโลก (ทรงกลม) และมักปรากฏเป็นเส้นโค้งบนแผนที่ที่มีการฉายภาพแบบเมอร์เคเตอร์ ส่วนที่ไม่ใช่จีโอเดสิกจะวาดเป็นเส้นตรงบนแผนที่

ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.geodesic() โดยที่ true ระบุว่าควรวาดส่วนต่างๆ เป็นเส้นโค้งจีโอเดสิก และ false ระบุว่าควรวาดส่วนต่างๆ เป็นเส้นตรง หากไม่ได้ระบุไว้ ค่าเริ่มต้นจะเป็นกลุ่มที่ไม่ใช่จีโอเดสิก (false)

หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงการตั้งค่าจีโอเดสิกได้โดยเรียกใช้ isGeodesic() และเปลี่ยนแปลงได้โดยเรียกใช้ setGeodesic()

ดัชนีลำดับ Z

ดัชนีลำดับ Z จะระบุลำดับการซ้อนกันของรูปร่างนี้ โดยสัมพันธ์กับภาพซ้อนทับอื่นๆ (รูปร่างอื่นๆ ภาพซ้อนทับบนพื้น และภาพซ้อนทับแบบเรียงต่อกัน) บนแผนที่ ภาพซ้อนทับที่มีดัชนีลำดับ Z สูงจะแสดงอยู่เหนือภาพซ้อนทับที่มีดัชนีลำดับ Z ต่ำกว่า ระบบจะวาดภาพซ้อนทับ 2 ภาพที่มีดัชนีลำดับ Z เดียวกันตามลำดับที่กำหนดเอง

โปรดทราบว่าระบบจะวาดเครื่องหมายไว้เหนือการวางซ้อนอื่นๆ เสมอ ไม่ว่าดัชนีลำดับ Z ของการวางซ้อนอื่นๆ จะเป็นอย่างไรก็ตาม

ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.zIndex() หากไม่ได้ระบุ ดัชนีลำดับ Z เริ่มต้นจะเป็น 0 หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงดัชนีลำดับ Z ได้โดยเรียกใช้ getZIndex() และเปลี่ยนแปลงได้โดยเรียกใช้ setZIndex()

ระดับการแชร์

การแสดงผลจะระบุว่าควรวาดรูปร่างบนแผนที่หรือไม่ โดย true หมายถึงควรวาด และ false หมายถึงไม่ควรวาด ซึ่งช่วยให้คุณไม่แสดงรูปร่างบนแผนที่ชั่วคราวได้ หากต้องการนำรูปร่างออกจากแผนที่อย่างถาวร ให้เรียกใช้ remove() ในรูปร่างนั้น

ตั้งค่าพร็อพเพอร์ตี้นี้ในออบเจ็กต์ตัวเลือกของรูปร่างโดยเรียกใช้ *Options.visible() หากไม่ได้ระบุ ระดับการเข้าถึงเริ่มต้นจะเป็น true หลังจากเพิ่มรูปร่างลงในแผนที่แล้ว คุณจะเข้าถึงระดับการมองเห็นได้โดยเรียกใช้ isVisible() และเปลี่ยนแปลงได้โดยเรียกใช้ setVisible()

เชื่อมโยงข้อมูลกับรูปร่าง

คุณสามารถจัดเก็บออบเจ็กต์ข้อมูลที่กำหนดเองด้วยเส้นประกอบ รูปหลายเหลี่ยม หรือวงกลมโดยใช้เมธอด setTag() ของรูปร่าง และเรียกข้อมูลออบเจ็กต์โดยใช้ getTag() ตัวอย่างเช่น เรียกใช้ Polyline.setTag() เพื่อจัดเก็บออบเจ็กต์ข้อมูลที่มีเส้นประกอบ และเรียกใช้ Polyline.getTag() เพื่อดึงข้อมูลออบเจ็กต์ข้อมูล

โค้ดด้านล่างกำหนดแท็กที่กำหนดเอง (A) สำหรับเส้นประกอบที่ระบุ

Kotlin

val polyline = map.addPolyline(
    PolylineOptions()
        .clickable(true)
        .add(
            LatLng(-35.016, 143.321),
            LatLng(-34.747, 145.592),
            LatLng(-34.364, 147.891),
            LatLng(-33.501, 150.217),
            LatLng(-32.306, 149.248),
            LatLng(-32.491, 147.309),
        ),
)
polyline?.tag = "A"

Java

Polyline polyline =
        map.addPolyline(
                (new PolylineOptions())
                        .clickable(true)
                        .add(
                                new LatLng(-35.016, 143.321),
                                new LatLng(-34.747, 145.592),
                                new LatLng(-34.364, 147.891),
                                new LatLng(-33.501, 150.217),
                                new LatLng(-32.306, 149.248),
                                new LatLng(-32.491, 147.309)));

polyline.setTag("A");

ต่อไปนี้คือตัวอย่างสถานการณ์ที่การจัดเก็บและดึงข้อมูลด้วยรูปร่างมีประโยชน์

  • แอปของคุณอาจรองรับรูปร่างประเภทต่างๆ และคุณต้องการจัดการรูปร่างเหล่านั้นแตกต่างกันเมื่อผู้ใช้คลิก
  • คุณอาจกำลังเชื่อมต่อกับระบบที่มีตัวระบุระเบียนที่ไม่ซ้ำกัน โดยรูปร่างจะแสดงถึงระเบียนที่เฉพาะเจาะจงในระบบนั้น
  • ข้อมูลรูปร่างอาจระบุลำดับความสำคัญเพื่อกำหนดดัชนีลำดับ Z สำหรับรูปร่าง