그리기 계층(라이브러리)
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
- 개요
- 라이브러리 사용
- DrawingManager 옵션
- 그리기 도구 컨트롤 업데이트
- 그리기 이벤트
개요
DrawingManager 클래스는 사용자에게 지도에 다각형, 직사각형, 다중선, 원, 마커를 그릴 수 있는 그래픽 인터페이스를 제공합니다.
라이브러리 사용
그리기 도구는 기본 지도 API JavaScript 코드와 별도로, 필요한 모든 기능이 포함된 독립 라이브러리입니다. 이 라이브러리에 포함된 기능을 사용하려면 먼저 지도 API 부트스트랩 URL의 libraries 매개변수를 사용하여 로드해야 합니다.
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=drawing&callback=initMap">
</script>
라이브러리 매개변수를 추가한 후 다음과 같이 DrawingManager 객체를 만들 수 있습니다.
var drawingManager = new google.maps.drawing.DrawingManager();
drawingManager.setMap(map);
DrawingManager 옵션
DrawingManager 생성자에는 표시할 컨트롤 집합, 컨트롤 위치 및 초기 그리기 상태를 정의하는 옵션 집합이 있습니다.
DrawingManager의 drawingMode 속성은 DrawingManager의 초기 그리기 상태를 정의하며, google.maps.drawing.OverlayType 상수가 허용됩니다. 기본값은 null로, 이 경우 DrawingManager가 초기화될 때 커서가 그리기 모드가 아닌 모드에 있습니다.DrawingManager의 drawingControl 속성은 지도에 그리기 도구 선택 인터페이스를 표시하는지 여부를 정의하며, 불리언 값이 허용됩니다.- 또한
DrawingManager의 drawingControlOptions 속성을 사용하여 컨트롤의 위치, 컨트롤에 표시해야 하는 오버레이의 유형도 정의할 수 있습니다.
- 각 오버레이 유형에는 처음 생성될 때 오버레이의 모양을 정의하는 기본 속성의 집합이 할당됩니다. 이는 오버레이의
{overlay}Options 속성에 정의됩니다(여기서 {overlay}가 오버레이 유형을 나타냅니다). 예를 들어 원의 채우기 속성, 획 속성, zIndex, 클릭 가능 여부는 circleOptions 속성을 사용하여 정의할 수 있습니다. 크기, 위치 또는 지도 값을 전달하면 무시됩니다.
설정 가능한 속성에 대한 자세한 내용은 API 참조 문서를 참고하세요.
참고: 도형을 만든 후 사용자가 편집 가능하도록 설정하려면 editable 속성을 true로 설정하세요.
DrawingManager 객체를 만든 후 setOptions()를 호출하고 새 값을 전달하여 업데이트할 수 있습니다.
drawingManager.setOptions({
drawingControlOptions: {
position: google.maps.ControlPosition.BOTTOM_LEFT,
drawingModes: ['marker']
}
});
그리기 도구 컨트롤을 숨기거나 표시하는 방법은 다음과 같습니다.
// To hide:
drawingManager.setOptions({
drawingControl: false
});
// To show:
drawingManager.setOptions({
drawingControl: true
});
map 객체에서 그리기 도구 컨트롤을 삭제하는 방법은 다음과 같습니다.
drawingManager.setMap(null);
그리기 컨트롤을 숨기면 그리기 도구 컨트롤이 표시되지 않지만 DrawingManager 클래스의 모든 기능은 계속 사용할 수 있습니다.
원하는 경우 이러한 방식으로 자신만의 컨트롤을 구현할 수 있습니다. map 객체에서 DrawingManager를 삭제하면 모든 그리기 기능이 사용 중지됩니다. 그리기 기능을 복원하려면 drawingManager.setMap(map) 또는 생성된 새 DrawingManager 객체로 지도에 다시 연결해야 합니다.
그리기 이벤트
도형 오버레이가 생성되면 두 개의 이벤트가 실행됩니다.
{overlay}complete 이벤트(여기서 {overlay}는 오버레이 유형(예: circlecomplete, polygoncomplete)을 나타냅니다). 오버레이에 대한 참조가 인수로 전달됩니다.overlaycomplete 이벤트. OverlayType 및 오버레이에 대한 참조가 포함된 객체 리터럴이 인수로 전달됩니다.
google.maps.event.addListener(drawingManager, 'circlecomplete', function(circle) {
var radius = circle.getRadius();
});
google.maps.event.addListener(drawingManager, 'overlaycomplete', function(event) {
if (event.type == 'circle') {
var radius = event.overlay.getRadius();
}
});
지도에 그리는 동안 click 및 mousemove와 같은 google.maps.Map 이벤트는 사용 중지됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-06(UTC)
[null,null,["최종 업데이트: 2025-08-06(UTC)"],[[["\u003cp\u003eThe \u003ccode\u003eDrawingManager\u003c/code\u003e class in the Google Maps JavaScript API enables users to draw shapes like polygons, circles, and markers directly on the map.\u003c/p\u003e\n"],["\u003cp\u003eTo utilize the Drawing Tools, include the \u003ccode\u003elibraries=drawing\u003c/code\u003e parameter in the Maps API bootstrap URL when loading the API.\u003c/p\u003e\n"],["\u003cp\u003eCustomize the drawing experience by configuring options like \u003ccode\u003edrawingMode\u003c/code\u003e, \u003ccode\u003edrawingControl\u003c/code\u003e, and shape-specific properties using the \u003ccode\u003eDrawingManager\u003c/code\u003e constructor and \u003ccode\u003esetOptions()\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eDrawing events such as \u003ccode\u003e{overlay}complete\u003c/code\u003e and \u003ccode\u003eoverlaycomplete\u003c/code\u003e are triggered when shapes are created, providing access to the drawn overlay for further manipulation.\u003c/p\u003e\n"],["\u003cp\u003eWhile drawing is active, standard Google Maps events like \u003ccode\u003eclick\u003c/code\u003e and \u003ccode\u003emousemove\u003c/code\u003e are temporarily disabled on the map.\u003c/p\u003e\n"]]],[],null,["1. [Overview](#overview)\n2. [Using the Library](#using_the_library)\n3. [DrawingManager Options](#drawingmanager_options)\n4. [Updating the Drawing Tools Control](#updating_the_drawing_tools_control)\n5. [Drawing Events](#drawing_events)\n\nOverview\n\nThe `DrawingManager` class provides a graphical interface for users to draw\npolygons, rectangles, polylines, circles, and markers on the map.\n\nUsing the Library\n\nThe Drawing Tools are a self-contained library, separate from the main Maps\nAPI JavaScript code. To use the functionality contained within this library,\nyou must first load it using the [`libraries`](/maps/documentation/javascript/libraries) parameter in the\nMaps API bootstrap URL: \n\n```html\n\u003cscript async\n src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=drawing&callback=initMap\"\u003e\n\u003c/script\u003e\n```\n\nOnce you've added the libraries parameter, you can create a `DrawingManager`\nobject as follows: \n\n```javascript\nvar drawingManager = new google.maps.drawing.DrawingManager();\ndrawingManager.setMap(map);\n```\n\nDrawingManager Options\n\nThe `DrawingManager` constructor takes a set of options that define the set of\ncontrols to display, the position of the control, and the initial drawing\nstate.\n\n- The `drawingMode` property of the `DrawingManager` defines the initial drawing state of the DrawingManager. It accepts a [`google.maps.drawing.OverlayType`](/maps/documentation/javascript/reference#OverlayType) constant. Default is `null`, in which case the cursor is in a non-drawing mode when the DrawingManager is initialized.\n- The `drawingControl` property of the `DrawingManager` defines the visibility of the drawing tools selection interface on the map. It accepts a boolean value.\n- You can also define the position of the control, and the types of overlays that should be represented in the control, using the `drawingControlOptions` property of the `DrawingManager`.\n - `position` defines the position of the drawing control on the map, and accepts a [`google.maps.ControlPosition`](/maps/documentation/javascript/reference#ControlPosition) constant.\n - `drawingModes` is an array of [`google.maps.drawing.OverlayType`](/maps/documentation/javascript/reference#OverlayType) constants, and defines the overlay types to include in the drawing control shape picker. The hand icon will always be present, allowing the user to interact with the map without drawing. The order of the tools in the control will match the order in which they are declared in the array.\n- Each type of overlay can be assigned a set of default properties, that define the appearance of the overlay when first created. These are defined in that overlay's `{overlay}Options` property (where `{overlay}` represents the overlay type). For example, a circle's fill properties, stroke properties, zIndex, and clickability can be defined with the `circleOptions` property. If any size, location, or map values are passed, they are ignored. For full details of which properties can be set, refer to the [API Reference documentation](/maps/documentation/javascript/reference#DrawingManagerOptions).\n\n**Note:** To make a shape [user-editable](/maps/documentation/javascript/shapes#editable) after it has\nbeen created, set its `editable` property to `true`. \n\nTypeScript \n\n```typescript\n// This example requires the Drawing library. Include the libraries=drawing\n// parameter when you first load the API. For example:\n// \u003cscript src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=drawing\"\u003e\n\nfunction initMap(): void {\n const map = new google.maps.Map(\n document.getElementById(\"map\") as HTMLElement,\n {\n center: { lat: -34.397, lng: 150.644 },\n zoom: 8,\n }\n );\n\n const drawingManager = new google.maps.drawing.DrawingManager({\n drawingMode: google.maps.drawing.OverlayType.MARKER,\n drawingControl: true,\n drawingControlOptions: {\n position: google.maps.ControlPosition.TOP_CENTER,\n drawingModes: [\n google.maps.drawing.OverlayType.MARKER,\n google.maps.drawing.OverlayType.CIRCLE,\n google.maps.drawing.OverlayType.POLYGON,\n google.maps.drawing.OverlayType.POLYLINE,\n google.maps.drawing.OverlayType.RECTANGLE,\n ],\n },\n markerOptions: {\n icon: \"https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png\",\n },\n circleOptions: {\n fillColor: \"#ffff00\",\n fillOpacity: 1,\n strokeWeight: 5,\n clickable: false,\n editable: true,\n zIndex: 1,\n },\n });\n\n drawingManager.setMap(map);\n}\n\ndeclare global {\n interface Window {\n initMap: () =\u003e void;\n }\n}\nwindow.initMap = initMap;https://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/samples/drawing-tools/index.ts#L8-L55\n```\n| **Note:** Read the [guide](/maps/documentation/javascript/using-typescript) on using TypeScript and Google Maps.\n\nJavaScript \n\n```javascript\n// This example requires the Drawing library. Include the libraries=drawing\n// parameter when you first load the API. For example:\n// \u003cscript src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=drawing\"\u003e\nfunction initMap() {\n const map = new google.maps.Map(document.getElementById(\"map\"), {\n center: { lat: -34.397, lng: 150.644 },\n zoom: 8,\n });\n const drawingManager = new google.maps.drawing.DrawingManager({\n drawingMode: google.maps.drawing.OverlayType.MARKER,\n drawingControl: true,\n drawingControlOptions: {\n position: google.maps.ControlPosition.TOP_CENTER,\n drawingModes: [\n google.maps.drawing.OverlayType.MARKER,\n google.maps.drawing.OverlayType.CIRCLE,\n google.maps.drawing.OverlayType.POLYGON,\n google.maps.drawing.OverlayType.POLYLINE,\n google.maps.drawing.OverlayType.RECTANGLE,\n ],\n },\n markerOptions: {\n icon: \"https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png\",\n },\n circleOptions: {\n fillColor: \"#ffff00\",\n fillOpacity: 1,\n strokeWeight: 5,\n clickable: false,\n editable: true,\n zIndex: 1,\n },\n });\n\n drawingManager.setMap(map);\n}\n\nwindow.initMap = initMap;https://github.com/googlemaps/js-samples/blob/2683f7366fb27829401945d2a7e27d77ed2df8e5/dist/samples/drawing-tools/docs/index.js#L7-L44\n```\n| **Note:** The JavaScript is compiled from the TypeScript snippet.\n[View example](/maps/documentation/javascript/examples/drawing-tools)\n\nTry Sample \n[JSFiddle.net](https://jsfiddle.net/gh/get/library/pure/googlemaps/js-samples/tree/master/dist/samples/drawing-tools/jsfiddle) [Google Cloud Shell](https://ssh.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Fgooglemaps%2Fjs-samples&cloudshell_git_branch=sample-drawing-tools&cloudshell_tutorial=cloud_shell_instructions.md&cloudshell_workspace=.)\n\nUpdating the Drawing Tools Control\n\nOnce the `DrawingManager` object has been created, you can update it by\ncalling `setOptions()` and passing new values. \n\n```javascript\ndrawingManager.setOptions({\n drawingControlOptions: {\n position: google.maps.ControlPosition.BOTTOM_LEFT,\n drawingModes: ['marker']\n }\n});\n```\n\nTo hide or show the drawing tools control: \n\n```javascript\n// To hide:\ndrawingManager.setOptions({\n drawingControl: false\n});\n\n// To show:\ndrawingManager.setOptions({\n drawingControl: true\n});\n```\n\nTo remove the drawing tools control from the `map` object: \n\n```javascript\ndrawingManager.setMap(null);\n```\n\n*Hiding* the drawing control causes the drawing tools control to not display,\nbut all of the functionality of the `DrawingManager` class is still available.\nIn this way, you can implement your own control, if desired. *Removing* the\n`DrawingManager` from the `map` object disables all drawing functionality; it\nmust be reattached to the map with `drawingManager.setMap(map)`, or a new\n`DrawingManager` object constructed, if drawing features are to be restored.\n\nDrawing Events\n\nWhen a shape overlay is created, two events are fired:\n\n- An `{overlay}complete` event (where `{overlay}` represents the overlay type, such as `circlecomplete`, `polygoncomplete`, etc). A reference to the overlay is passed as an argument.\n- An `overlaycomplete` event. An object literal, containing the `OverlayType` and a reference to the overlay, is passed as an argument.\n\n```javascript\ngoogle.maps.event.addListener(drawingManager, 'circlecomplete', function(circle) {\n var radius = circle.getRadius();\n});\n\ngoogle.maps.event.addListener(drawingManager, 'overlaycomplete', function(event) {\n if (event.type == 'circle') {\n var radius = event.overlay.getRadius();\n }\n});\n```\n\nNote that [`google.maps.Map`](/maps/documentation/javascript/reference#Map)\nevents, such as `click` and `mousemove` are disabled while drawing on the map."]]
