Tài liệu tham khảo về kiểu cho API Maps JavaScript

Chọn nền tảng: Android iOS JavaScript

Với các tuỳ chọn kiểu, bạn có thể tuỳ chỉnh cách trình bày các kiểu bản đồ chuẩn của Google, thay đổi cách hiển thị trực quan của các đối tượng như đường, công viên, doanh nghiệp và các địa điểm yêu thích khác. Ngoài việc thay đổi kiểu của các đối tượng này, bạn có thể ẩn hoàn toàn các đối tượng. Điều này có nghĩa là bạn có thể nhấn mạnh các thành phần cụ thể của bản đồ hoặc làm cho bản đồ phù hợp với kiểu của trang xung quanh.

Nếu bạn muốn cập nhật cùng một kiểu trên nhiều ứng dụng, hãy xem phần tuỳ chỉnh trên đám mây. Tính năng này có trong Google Cloud Console và yêu cầu mã bản đồ. Để tránh xung đột tiềm ẩn, đừng kết hợp tính năng tuỳ chỉnh trên đám mây và kiểu được cố định giá trị trong mã trong cùng một ứng dụng.

Để có trải nghiệm định kiểu toàn diện hơn, bạn có thể sử dụng kiểu JSON với tính năng định kiểu bản đồ dựa trên đám mây. Tính năng này cung cấp danh sách các đối tượng trên bản đồ phong phú hơn và nhiều lựa chọn tuỳ chỉnh hơn. Giản đồ JSON của tính năng định kiểu bản đồ dựa trên đám mây không tương thích ngược với các nội dung khai báo kiểu JSON được nhúng. Điều này có nghĩa là bạn không thể sử dụng trực tiếp JSON của tính năng định kiểu bản đồ dựa trên đám mây trong API JavaScript của Maps. Tuy nhiên, bạn có thể nhập nội dung khai báo kiểu JSON được nhúng vào giản đồ JSON của tính năng định kiểu bản đồ dựa trên đám mây.

Ví dụ

Nội dung khai báo kiểu JSON sau đây sẽ chuyển tất cả các đối tượng trên bản đồ thành màu xám, sau đó tô màu xanh dương cho hình dạng đường trục và ẩn hoàn toàn nhãn cảnh quan:

[
  {
    "featureType": "all",
    "stylers": [
      { "color": "#C0C0C0" }
    ]
  },{
    "featureType": "road.arterial",
    "elementType": "geometry",
    "stylers": [
      { "color": "#CCFFFF" }
    ]
  },{
    "featureType": "landscape",
    "elementType": "labels",
    "stylers": [
      { "visibility": "off" }
    ]
  }
]

Để áp dụng nội dung khai báo kiểu JSON cho bản đồ, hãy truyền mảng kiểu vào thuộc tính MapOptions.styles khi tạo bản đồ hoặc gọi Map.setOptions(). Để xem ví dụ hoàn chỉnh về cách sử dụng định kiểu JSON trong ứng dụng, hãy xem phần Lựa chọn bản đồ phong cách riêng.

Đối tượng JSON

Nội dung khai báo kiểu JSON bao gồm các phần tử sau:

• featureType (không bắt buộc) – các đối tượng cần chọn để sửa đổi kiểu này. Đối tượng là các đặc điểm địa lý trên bản đồ, bao gồm đường, công viên, vùng nước và nhiều đối tượng khác. Nếu bạn không chỉ định một tính năng, thì tất cả các tính năng sẽ được chọn.
• elementType (không bắt buộc) – thuộc tính của đối tượng được chỉ định để chọn. Phần tử là các phần phụ của một đối tượng, bao gồm cả nhãn và hình học. Nếu bạn không chỉ định một phần tử, thì tất cả phần tử của tính năng sẽ được chọn.
• stylers – các quy tắc áp dụng cho các đối tượng và thành phần đã chọn. Trình tạo kiểu cho biết màu sắc, chế độ hiển thị và trọng số của đối tượng. Bạn có thể áp dụng một hoặc nhiều kiểu cho một đối tượng.

Để chỉ định một kiểu, bạn phải kết hợp một tập hợp bộ chọn featureType và elementType cũng như stylers của bạn vào một mảng kiểu. Bạn có thể nhắm đến bất kỳ tổ hợp tính năng nào trong một mảng. Tuy nhiên, số lượng kiểu bạn có thể áp dụng cùng một lúc là có giới hạn. Nếu mảng kiểu của bạn vượt quá số ký tự tối đa, thì không có kiểu nào được áp dụng.

Phần còn lại của trang này có thêm thông tin về các đối tượng, thành phần và bộ tạo kiểu.

featureType

Đoạn mã JSON sau đây chọn tất cả các đường trên bản đồ:

{
  "featureType": "road"
}

Đối tượng hoặc loại đối tượng là các đặc điểm địa lý trên bản đồ, bao gồm đường, công viên, vùng nước, doanh nghiệp, v.v.

Các tính năng tạo thành một cây danh mục, trong đó all là gốc. Nếu bạn không chỉ định tính năng, thì tất cả tính năng sẽ được chọn. Việc chỉ định một tính năng của all cũng có tác dụng tương tự.

Một số tính năng chứa các tính năng con mà bạn chỉ định bằng ký hiệu dấu chấm. Ví dụ: landscape.natural hoặc road.local. Nếu bạn chỉ chỉ định đối tượng gốc, chẳng hạn như road, thì kiểu bạn chỉ định cho đối tượng gốc sẽ áp dụng cho tất cả đối tượng con, chẳng hạn như road.local và road.highway.

Lưu ý rằng các tính năng mẹ có thể bao gồm một số thành phần không có trong tất cả các tính năng con.

Bạn có thể sử dụng các tính năng sau:

• all (mặc định) chọn tất cả tính năng.
• administrative chọn tất cả khu vực hành chính. Kiểu chỉ ảnh hưởng đến nhãn của khu vực hành chính, chứ không ảnh hưởng đến đường biên giới địa lý hoặc màu nền.
  • administrative.country chọn quốc gia.
  • administrative.land_parcel chọn các lô đất.
  • administrative.locality chọn địa phương.
  • administrative.neighborhood chọn vùng lân cận.
  • administrative.province chọn tỉnh.
• landscape chọn tất cả hướng ngang.
  • landscape.man_made chọn các đối tượng nhân tạo, chẳng hạn như toà nhà và các công trình khác.
  • landscape.natural chọn các đối tượng tự nhiên, chẳng hạn như núi, sông, sa mạc và sông băng.
  • landscape.natural.landcover chọn các đối tượng lớp phủ đất, vật liệu vật lý bao phủ bề mặt trái đất, chẳng hạn như rừng, đồng cỏ, vùng đất ngập nước và đất trống.
  • landscape.natural.terrain chọn các đặc điểm địa hình của bề mặt đất, chẳng hạn như độ cao, độ dốc và hướng.
• poi chọn tất cả các điểm yêu thích.
  • poi.attraction chọn các điểm tham quan du lịch.
  • poi.business chọn doanh nghiệp.
  • poi.government chọn toà nhà chính phủ.
  • poi.medical chọn các dịch vụ khẩn cấp, bao gồm bệnh viện, hiệu thuốc, cảnh sát, bác sĩ và các dịch vụ khác.
  • poi.park chọn công viên.
  • poi.place_of_worship chọn nơi thờ tự, bao gồm nhà thờ, đền chùa, nhà thờ Hồi giáo và các nơi khác.
  • poi.school chọn trường học.
  • poi.sports_complex chọn tổ hợp thể thao.
• road chọn tất cả các đường.
  • road.arterial chọn đường chính.
  • road.highway chọn đường cao tốc.
  • road.highway.controlled_access chọn đường cao tốc có kiểm soát lối ra vào.
  • road.local chọn đường nội đô.
• transit chọn tất cả các trạm và tuyến phương tiện công cộng.
  • transit.line chọn các tuyến phương tiện công cộng.
  • transit.station chọn tất cả trạm phương tiện công cộng.
  • transit.station.airport chọn sân bay.
  • transit.station.bus chọn trạm xe buýt.
  • transit.station.rail chọn ga tàu hoả.
• water chọn các vùng nước.

elementType

Đoạn mã JSON sau đây chọn nhãn cho tất cả đường địa phương:

{
  "featureType": "road.local",
  "elementType": "labels"
}

Phần tử là các phân mục của một tính năng. Ví dụ: một con đường bao gồm đường đồ hoạ (hình học) trên bản đồ và văn bản biểu thị tên của con đường đó (nhãn).

Các phần tử sau đây có sẵn, nhưng xin lưu ý rằng một tính năng cụ thể có thể không hỗ trợ, hỗ trợ một số hoặc tất cả các phần tử:

Màu của văn bản nhãn fill và stroke thay đổi dựa trên mức thu phóng. Để đảm bảo trải nghiệm nhất quán trên các mức thu phóng, hãy luôn xác định cả fill và stroke.

• all (mặc định) chọn tất cả các phần tử của đối tượng được chỉ định.
• geometry chọn tất cả các phần tử hình học của đối tượng được chỉ định.
  • geometry.fill chỉ chọn màu nền của hình dạng đối tượng.
  • geometry.stroke chỉ chọn nét vẽ của hình học đối tượng.
• labels chọn nhãn văn bản liên kết với tính năng được chỉ định.
  • labels.icon chỉ chọn biểu tượng xuất hiện trong nhãn của tính năng.
  • labels.text chỉ chọn văn bản của nhãn.
  • labels.text.fill chỉ chọn màu nền của nhãn. Màu nền của nhãn thường được hiển thị dưới dạng đường viền màu bao quanh văn bản nhãn.
  • labels.text.stroke chỉ chọn nét vẽ của văn bản nhãn.

stylers

Trình tạo kiểu là các tuỳ chọn định dạng mà bạn có thể áp dụng cho các đối tượng và thành phần trên bản đồ.

Đoạn mã JSON sau đây hiển thị một đối tượng địa lý có màu xanh lục sáng, sử dụng giá trị RGB:

"stylers": [
  { "color": "#99FF33" }
]

Đoạn mã này loại bỏ tất cả cường độ khỏi màu của một đối tượng, bất kể màu bắt đầu của đối tượng đó. Hiệu ứng này là để hiển thị tính năng thang màu xám:

"stylers": [
  { "saturation": -100 }
]

Đoạn mã này ẩn hoàn toàn một tính năng:

    "stylers": [
      { "visibility": "off" }
    ]

Các tuỳ chọn kiểu sau đây được hỗ trợ:

• hue (chuỗi thập lục phân RGB có định dạng #RRGGBB) cho biết màu cơ bản.

  Lưu ý: Tuỳ chọn này đặt sắc độ trong khi vẫn giữ nguyên độ bão hoà và độ sáng được chỉ định trong kiểu mặc định của Google (hoặc trong các tuỳ chọn kiểu khác mà bạn xác định trên bản đồ). Màu thu được sẽ tương ứng với kiểu của bản đồ cơ sở. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các đối tượng trên bản đồ được tạo kiểu bằng hue. Tốt hơn là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

• lightness (giá trị dấu phẩy động từ -100 đến 100) cho biết mức thay đổi theo tỷ lệ phần trăm về độ sáng của phần tử. Giá trị âm làm tăng độ tối (trong đó -100 là màu đen) trong khi giá trị dương làm tăng độ sáng (trong đó +100 là màu trắng).

  Lưu ý: Tuỳ chọn này đặt độ sáng trong khi vẫn giữ độ bão hoà và sắc độ được chỉ định trong kiểu mặc định của Google (hoặc trong các tuỳ chọn kiểu khác mà bạn xác định trên bản đồ). Màu thu được sẽ tương ứng với kiểu của bản đồ cơ sở. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các đối tượng trên bản đồ được tạo kiểu bằng lightness. Tốt hơn hết là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

• saturation (giá trị dấu phẩy động từ -100 đến 100) cho biết mức thay đổi theo tỷ lệ phần trăm về cường độ của màu cơ bản cần áp dụng cho phần tử.

  Lưu ý: Tuỳ chọn này đặt độ bão hoà trong khi vẫn giữ nguyên sắc độ và độ sáng được chỉ định trong kiểu mặc định của Google (hoặc trong các tuỳ chọn kiểu khác mà bạn xác định trên bản đồ). Màu thu được sẽ tương ứng với kiểu của bản đồ cơ sở. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các đối tượng trên bản đồ được tạo kiểu bằng saturation. Tốt hơn là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

• gamma (giá trị dấu phẩy động từ 0.01 đến 10.0, trong đó 1.0 không áp dụng hiệu chỉnh) cho biết mức hiệu chỉnh gamma cần áp dụng cho phần tử. Hiệu chỉnh gamma sửa đổi độ sáng của màu sắc theo cách phi tuyến tính, trong khi không ảnh hưởng đến giá trị màu trắng hoặc đen. Hiệu chỉnh gamma thường được dùng để sửa đổi độ tương phản của nhiều phần tử. Ví dụ: bạn có thể sửa đổi gamma để tăng hoặc giảm độ tương phản giữa các cạnh và phần bên trong của các phần tử.

  Lưu ý: Tuỳ chọn này điều chỉnh độ sáng tương ứng với kiểu mặc định của Google, sử dụng đường cong gamma. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các đối tượng trên bản đồ được tạo kiểu bằng gamma. Tốt hơn là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

• invert_lightness (nếu true) đảo ngược độ sáng hiện có. Ví dụ: điều này rất hữu ích khi bạn muốn nhanh chóng chuyển sang bản đồ tối hơn có văn bản màu trắng.

  Lưu ý: Lựa chọn này chỉ đơn giản là đảo ngược kiểu mặc định của Google. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các đối tượng trên bản đồ được tạo kiểu bằng invert_lightness. Tốt hơn là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

• visibility (on, off hoặc simplified) cho biết liệu phần tử có xuất hiện trên bản đồ hay không và xuất hiện như thế nào. Chế độ hiển thị simplified sẽ xoá một số tính năng về kiểu khỏi các đối tượng bị ảnh hưởng; ví dụ: đường được đơn giản hoá thành các đường mỏng hơn mà không có đường viền, trong khi công viên mất văn bản nhãn nhưng vẫn giữ lại biểu tượng nhãn.
• color (chuỗi thập lục phân RGB có định dạng #RRGGBB) đặt màu của đối tượng.
• weight (giá trị số nguyên, lớn hơn hoặc bằng 0) đặt trọng số của đối tượng, tính bằng pixel. Việc đặt trọng số thành giá trị cao có thể dẫn đến việc cắt bớt gần đường viền ô.

Các quy tắc về kiểu được áp dụng theo thứ tự mà bạn chỉ định. Đừng kết hợp nhiều thao tác thành một thao tác kiểu duy nhất. Thay vào đó, hãy xác định từng thao tác dưới dạng một mục riêng biệt trong mảng kiểu.

Lưu ý: Thứ tự rất quan trọng vì một số phép toán không có tính giao hoán. Các đối tượng và/hoặc phần tử được sửa đổi thông qua thao tác kiểu (thường) đã có kiểu hiện tại. Các thao tác sẽ tác động đến những kiểu hiện có đó (nếu có).

Mô hình sắc độ, độ rực màu, độ sáng

Lưu ý: Hiệu ứng của chế độ cài đặt sắc độ, độ bão hoà, độ sáng và hệ số gamma có liên quan đến kiểu của bản đồ cơ sở. Nếu Google thực hiện bất kỳ thay đổi nào đối với kiểu bản đồ cơ sở, thì những thay đổi đó sẽ ảnh hưởng đến các tính năng của bản đồ được tạo kiểu bằng các tuỳ chọn này. Tốt hơn là bạn nên sử dụng trình tạo kiểu color tuyệt đối nếu có thể.

Bản đồ phong cách riêng sử dụng mô hình màu sắc, độ bão hoà, độ sáng (HSL) để biểu thị màu trong các thao tác của bộ định kiểu. Sắc độ cho biết màu cơ bản, độ bão hoà cho biết cường độ của màu đó và độ sáng cho biết lượng màu trắng hoặc đen tương đối trong màu cấu thành.

Hiệu chỉnh gamma sửa đổi độ sáng trên không gian màu, thường là để tăng hoặc giảm độ tương phản. Ngoài ra, mô hình HSL xác định màu trong không gian toạ độ, trong đó hue cho biết hướng trong bánh xe màu, còn độ bão hoà và độ sáng cho biết biên độ dọc theo các trục khác nhau. Sắc thái màu được đo trong không gian màu sắc RGB, tương tự như hầu hết các không gian màu sắc RGB, ngoại trừ việc không có sắc thái trắng và đen.

Mặc dù hue lấy giá trị mã màu hex HTML, nhưng giá trị này chỉ được dùng để xác định màu cơ bản – tức là hướng của màu trên bánh xe màu, chứ không phải độ rực màu hay độ sáng của màu (được biểu thị riêng dưới dạng phần trăm thay đổi).

Ví dụ: bạn có thể xác định sắc độ cho màu xanh lục thuần khiết là hue:0x00ff00 hoặc hue:0x000100. Cả hai sắc thái đều giống hệt nhau. Cả hai giá trị đều trỏ đến màu xanh lục thuần tuý trong mô hình màu HSL.

Bánh xe màu RGB

Giá trị RGB hue bao gồm các phần bằng nhau của màu đỏ, xanh lục và xanh dương không cho biết sắc độ, vì không có giá trị nào trong số đó cho biết hướng trong không gian toạ độ HSL. Ví dụ: "#000000" (đen), "#FFFFFF" (trắng) và tất cả các sắc thái màu xám thuần tuý. Để chỉ định màu đen, trắng hoặc xám, bạn phải xoá tất cả saturation (đặt giá trị thành -100) và điều chỉnh lightness.

Ngoài ra, khi sửa đổi các tính năng hiện có đã có bảng phối màu, việc thay đổi một giá trị như hue sẽ không thay đổi saturation hoặc lightness hiện có.