From 53a1ca5c11fce691121368bb9796ce43de704e4f Mon Sep 17 00:00:00 2001 From: Denis Karavaev Date: Thu, 19 May 2016 12:34:44 +0600 Subject: [PATCH] complete basic-types.md --- src/doc/en/manual/basic-types.md | 667 ++++++++++++++++++++++++++++++ src/doc/manual/base-types.md | 567 +++++++++++++++++++++++++ src/doc/ru/manual/base-classes.md | 172 ++++++++ src/doc/ru/manual/basic-types.md | 660 +++++++++++++++++++++++++++++ src/doc/ru/manual/utils.md | 476 +++++++++++++++++++++ 5 files changed, 2542 insertions(+) create mode 100644 src/doc/en/manual/basic-types.md create mode 100644 src/doc/manual/base-types.md create mode 100644 src/doc/ru/manual/base-classes.md create mode 100644 src/doc/ru/manual/basic-types.md create mode 100644 src/doc/ru/manual/utils.md diff --git a/src/doc/en/manual/basic-types.md b/src/doc/en/manual/basic-types.md new file mode 100644 index 000000000..2c0a86d22 --- /dev/null +++ b/src/doc/en/manual/basic-types.md @@ -0,0 +1,667 @@ +## Basic Types + +{toc} + +### Description + +This section describes the classes of basic data types that are often found in the pages of maps API guide and +required for use with many maps API objects. + +### DG.LatLng + +Represents a geographical point with a certain latitude and longitude. + + var latlng = DG.latLng(54.98, 82.89); + +All methods that accept LatLng objects also accept them in a simple Array form and simple object form +(unless noted otherwise), so these lines are equivalent: + + map.panTo([54.98, 82.89]); + map.panTo({lon: 82.89, lat: 54.98}); + map.panTo({lat: 54.98, lng: 82.89}); + map.panTo(DG.latLng(54.98, 82.89)); + +#### Constructor + + + + + + + + + + + + + + + + + + + + + + +
FactoryDescription
DG.latLng( + <Number> latitude, + <Number> longitude, + <Number> altitude? ) + Creates an object representing a geographical point with the given latitude and longitude + (and optionally altitude).
DG.latLng( + <Array> coords ) + Expects an array of the form [Number, Number] or [Number, Number, Number] + instead.
DG.latLng( + <Object> coords ) + Expects an plain object of the form {lat: Number, lng: Number} or + {lat: Number, lng: Number, alt: Number} instead.
+ +#### Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodReturnsDescription
equals( + <LatLng> otherLatLng, + <Number> maxMargin? ) + BooleanReturns true if the given LatLng point is at the + same position (within a small margin of error). The margin of error can be overriden by setting + maxMargin to a small number.
toString()StringReturns a string representation of the point (for debugging purposes).
distanceTo( + <LatLng> otherLatLng ) + NumberReturns the distance (in meters) to the given LatLng + calculated using the Haversine formula.
wrap()LatLngReturns a new LatLng object with the longitude wrapped + so it's always between -180 and +180 degrees.
toBounds( + <Number> sizeInMeters ) + LatLngBoundsReturns a new LatLngBounds object in which each boundary + is sizeInMeters meters apart from the LatLng.
+ +#### Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
latNumberLatitude in degrees.
lngNumberLongitude in degrees.
altNumberAltitude in meters (optional).
+ +### DG.LatLngBounds + +Represents a rectangular geographical area on a map. + + var southWest = DG.latLng(54.9801, 82.8974), + northEast = DG.latLng(54.9901, 82.9074), + bounds = DG.latLngBounds(southWest, northEast); + +All methods that accept LatLngBounds objects also accept them in a simple Array form (unless noted otherwise), +so the bounds example above can be passed like this: + + map.fitBounds([ + [54.9801, 82.8974], + [54.9901, 82.9074] + ]); + +#### Creation + + + + + + + + + + + + + + + + + + +
FactoryDescription
DG.latLngBounds( + <LatLng> southWest, + <LatLng> northEast ) + Creates a LatLngBounds object by defining south-west + and north-east corners of the rectangle.
DG.latLngBounds( + <LatLng[]> latlngs) + Creates a LatLngBounds object defined by the geographical + points it contains. Very useful for zooming the map to fit a particular set of locations with + fitBounds.
+ +#### Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodReturnsDescription
extend( + <LatLng> latlng ) + thisExtend the bounds to contain the given point.
extend( + <LatLngBounds> otherBounds ) + thisExtend the bounds to contain the given bounds.
pad( + <Number> bufferRatio ) + LatLngBoundsReturns bigger bounds created by extending the current bounds by a given percentage in each direction.
getCenter()LatLng
getSouthWest()LatLngReturns the south-west point of the bounds.
getNorthEast()LatLngReturns the north-east point of the bounds.
getNorthWest()LatLngReturns the north-west point of the bounds.
getSouthEast()LatLngReturns the south-east point of the bounds.
getWest()NumberReturns the west longitude of the bounds.
getSouth()NumberReturns the south latitude of the bounds.
getEast()NumberReturns the east longitude of the bounds.
getNorth()NumberReturns the north latitude of the bounds.
contains( + <LatLngBounds> otherBounds ) + BooleanReturns true if the rectangle contains the given one.
contains( + <LatLng> latlng ) + BooleanReturns true if the rectangle contains the given point.
intersects( + <LatLngBounds> otherBounds ) + BooleanReturns true if the rectangle intersects the given bounds. Two bounds intersect + if they have at least one point in common.
overlaps( + <Bounds> otherBounds ) + BooleanReturns true if the rectangle overlaps the given bounds. Two bounds overlap + if their intersection is an area.
toBBoxString()StringReturns a string with bounding box coordinates in a + 'southwest_lng,southwest_lat,northeast_lng,northeast_lat' format. Useful for sending + requests to web services that return geo data.
equals( + <LatLngBounds> otherBounds ) + BooleanReturns true if the rectangle is equivalent (within a small margin of error) + to the given bounds.
isValid()BooleanReturns true if the bounds are properly initialized.
+ +### DG.Point + +Represents a point with x and y coordinates in pixels. + + var point = DG.point(200, 300); + +All methods and options that accept Point objects also accept them in a simple Array form +(unless noted otherwise), so these lines are equivalent: + + map.panBy([200, 300]); + map.panBy(DG.point(200, 300)); + +#### Creation + + + + + + + + + + + + + + + + + + +
FactoryDescription
DG.point( + <Number> x, + <Number> y, + <Boolean> round? ) + Creates a Point object with the given x and y coordinates. + If optional round is set to true, rounds the x and y values.
DG.point( + <Number[]> coords) + Expects an array of the form [x, y] instead.
+ +#### Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodReturnsDescription
clone()PointReturns a copy of the current point.
add( + <Point> otherPoint ) + PointReturns the result of addition of the current and the given points.
subtract( + <Point> otherPoint ) + PointReturns the result of subtraction of the given point from the current.
divideBy( + <Number> num ) + PointReturns the result of division of the current point by the given number.
multiplyBy( + <Number> num ) + PointReturns the result of multiplication of the current point by the given number.
scaleBy( + <Point> scale ) + PointMultiply each coordinate of the current point by each coordinate of + scale. In linear algebra terms, multiply the point by the + scaling matrix + defined by scale.
unscaleBy( + <Point> scale ) + PointInverse of scaleBy. Divide each coordinate of the current point by + each coordinate of scale.
round()PointReturns a copy of the current point with rounded coordinates.
floor()PointReturns a copy of the current point with floored coordinates (rounded down).
ceil()PointReturns a copy of the current point with ceiled coordinates (rounded up).
distanceTo( + <Point> otherPoint ) + NumberReturns the cartesian distance between the current and the given points.
equals( + <Point> otherPoint ) + BooleanReturns true if the given point has the same coordinates.
contains( + <Point> otherPoint ) + BooleanReturns true if both coordinates of the given point are less than + the corresponding current point coordinates (in absolute values).
toString()StringReturns a string representation of the point for debugging purposes.
+ +#### Properties + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
xNumberx coordinate.
yNumbery coordinate.
+ +### DG.Bounds + +Represents a rectangular area in pixel coordinates. + + var p1 = DG.point(10, 10), + p2 = DG.point(40, 60), + bounds = DG.bounds(p1, p2); + +All methods that accept Bounds objects also accept them in a simple Array form +(unless noted otherwise), so the bounds example above can be passed like this:

+ + otherBounds.intersects([[10, 10], [40, 60]]); + +#### Creation + + + + + + + + + + + + + + + + + + +
FactoryDescription
DG.bounds( + <Point> topLeft, + <Point> bottomRight ) + Creates a Bounds object from two coordinates (usually top-left and bottom-right corners).
DG.bounds( + <Point[]> points ) + Creates a Bounds object from the points it contains.
+ +#### Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodReturnsDescription
extend( + <Point> point ) + thisExtends the bounds to contain the given point.
getCenter( + <Boolean> round? ) + PointReturns the center point of the bounds.
getBottomLeft()PointReturns the bottom-left point of the bounds.
getTopRight()PointReturns the top-right point of the bounds.
getSize()PointReturns the size of the given bounds.
contains( + <Bounds> otherBounds ) + BooleanReturns true if the rectangle contains the given one.
contains( + <Point> point ) + BooleanReturns true if the rectangle contains the given poing.
intersects( + <Bounds> otherBounds ) + BooleanReturns true if the rectangle intersects the given bounds. Two bounds + intersect if they have at least one point in common.
overlaps( + <Bounds> otherBounds ) + BooleanReturns true if the rectangle overlaps the given bounds. Two bounds + overlap if their intersection is an area.
+ +#### Properties + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
minPointThe top left corner of the rectangle.
maxPointThe bottom right corner of the rectangle.
diff --git a/src/doc/manual/base-types.md b/src/doc/manual/base-types.md new file mode 100644 index 000000000..44ef89ffc --- /dev/null +++ b/src/doc/manual/base-types.md @@ -0,0 +1,567 @@ +## Базовые классы + +{toc} + +### Описание + +В данном разделе описаны базовые классы, которые часто встречаются на страницах руководства API карт и необходимы для работы с многими объектами карты. + +### Класс DG.LatLng + +Географическая точка с определенной широтой и долготой. + + var latlng = DG.latLng(54.98, 82.89); + +Все методы, которые принимают объекты LatLng также принимают широту и долготу в виде простого массива или объекта, то есть данные записи эквивалентны: + + map.panTo(DG.latLng(54.98, 82.89)); + map.panTo([54.98, 82.89]); + map.panTo({lng: 82.89, lat: 54.98}); + map.panTo({lat: 54.98, lng: 82.89}); + +#### Конструктор + + + + + + + + + + + + + + + + +
КонструкторИспользованиеОписание
+ DG.LatLng( + <Number> latitude, + <Number> longitude, + <Number> altitude? ) + + DG.latLng(…) + DG.latLng([…]) + Создает объект, представляющий географическую точку с определенной широтой и долготой (и опционально высотой).
+ +#### Свойства + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
latNumberШирота в градусах.
lngNumberДолгота в градусах.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
distanceTo( + <LatLng> otherLatlng ) + NumberВозвращает расстояние (в метрах) до переданной широты и долготы, рассчитывается по формуле Haversine. См. описание в Wikipedia
equals( + <LatLng> otherLatlng ) + BooleanВозвращает true, если переданная широта и долгота находится в той же позиции (с небольшой погрешностью).
toString()StringВозвращает строковое представление точки (для отладки).
+ +### Класс DG.LatLngBounds + +Прямоугольная географическая область на карте. + + var southWest = DG.latLng(54.9801, 82.8974), + northEast = DG.latLng(54.9901, 82.9074), + bounds = DG.latLngBounds(southWest, northEast); + +Все методы, которые принимают объекты LatLngBounds также принимают их в виде простого массива, то есть границы могут быть указаны как в этом примере: + + map.fitBounds([ + [54.9801, 82.8974], + [54.9901, 82.9074] + ]); + +#### Конструктор + + + + + + + + + + + + + + + + + + + + + + + +
КонструкторИспользованиеОписание
+ DG.LatLngBounds( + <LatLng> southWest, + <LatLng> northEast ) + + DG.latLngBounds(…)
+ DG.latLngBounds([…]) + 		Создает объект LatLngBounds с определенными юго-западным и северо-восточным углами прямоугольника.
DG.LatLngBounds( + <LatLng[]> latlng ) + + DG.latLngBounds(…) + Создает объект LatLngBounds на основе географических точек, которые находятся внутри. Удобно использовать, если необходимо подстроить центр и масштаб карты с помощью метода fitBounds.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
extend( + <LatLng | LatLngBounds> latlng ) + thisРасширяет границы таким образом, чтобы в них входила переданная точка или другие границы.
getSouthWest()LatLngВозвращает юго-западную точку границ.
getNorthEast()LatLngВозвращает северо-восточную точку границ.
getNorthWest()LatLngВозвращает северо-западную точку границ.
getSouthEast()LatLngВозвращает юго-восточную точку границ.
getWest()NumberВозвращает западную долготу границ.
getSouth()NumberВозвращает южную широту границ.
getEast()NumberВозвращает восточную долготу границ.
getNorth()NumberВозвращает северную широту границ.
getCenter()LatLngВозвращает центральную точку прямоугольной области.
contains( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если текущий прямоугольник содержит внутри себя переданный прямоугольник.
contains( + <LatLng> latlng ) + BooleanВозвращает true, если прямоугольник содержит внутри себя переданную точку.
intersects( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если текущий прямоугольник пересекается с переданным прямоугольником.
equals( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если текущий прямоугольник эквивалентен (с небольшой погрешностью) переданному прямоугольнику.
toBBoxString()String + Возвращает строку с координатами границ в формате 'southwest_lng,southwest_lat,northeast_lng,northeast_lat'. Удобно использовать для отправки запросов к веб-сервисам, возвращающим геоданные.
pad( + <Number> bufferRatio ) + LatLngBoundsВозвращает большие границы, созданные путем расширения текущих границ на заданный процент в каждом направлении.
isValid() + BooleanВозвращает true, если если свойства границ инициализированы.
+ +### Класс DG.Point + +Точка с пиксельными координатами x и y. + + var point = DG.point(200, 300); + +Все методы, которые принимают объекты Point также принимают координаты в виде простого массива, то есть данные записи эквивалентны: + + map.panBy([200, 300]); + map.panBy(DG.point(200, 300)); + +#### Конструктор + + + + + + + + + + + + + + + + + + +
КонструкторИспользованиеОписание
DG.Point( + <Number> x, <Number> y, + <Boolean> round? ) + + DG.point(…)
+ DG.point([…]) + 		Создает объект Point с координатами x и y. Если опциональный параметр round передан со значением true, тогда координаты будут округлены.
+ +#### Свойства + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
xNumberКоордината x.
yNumberКоордината y.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
add( + <Point> otherPoint ) + PointВозвращает результат сложения текущей и переданной точек.
subtract( + <Point> otherPoint ) + PointВозвращает результат вычитания переданной точки из текущей.
multiplyBy( + <Number> number ) + PointВозвращает результат умножения текущей точки на переданное число.
divideBy( + <Number> number, + <Boolean> round? ) + PointВозвращает результат деления текущей точки на переданное число. Если опциональный параметр round передан со значением true, тогда результат будет округлен.
distanceTo( + <Point> otherPoint ) + NumberВозвращает расстояние между текущей и переданной точками.
clone()PointВозвращает копию текущей точки.
round()PointВозвращает копию текущей точки с округленными координатами.
floor()PointВозвращает копию текущей точки с округленными в меньшую сторону координатами.
equals( + <Point> otherPoint ) + BooleanВозвращает true, если переданная точка имеет такие же координаты, как и текущая.
contains( + <Point> otherPoint ) + BooleanВозвращает true, если обе координаты переданной точки меньше соотвествующих координат текущей точки.
toString()StringВозвращает строковое представление точки (для отладки).
+ +### Класс DG.Bounds + +Прямоугольная область на карте в пиксельных координатах. + + var p1 = DG.point(10, 10), + p2 = DG.point(40, 60), + bounds = DG.bounds(p1, p2); + +Все методы, которые принимают объекты Bounds также принимают их в виде простого массива, то есть границы могут быть указаны как в этом примере: + + otherBounds.intersects([[10, 10], [40, 60]]); + +#### Конструктор + + + + + + + + + + + + + + + + + + + + + + + + + +
КонструкторИспользованиеОписание
DG.Bounds( + <Point> topLeft, + <Point> bottomRight ) + + DG.bounds(…)
+ DG.bounds([…]) + 		Создает объект Bounds на основе левого верхнего и правого нижнего углов.
DG.Bounds( + <Point[]> points ) + + DG.bounds(…) + Создает объект Bounds на основе точек, которые будут в него входить.
+ +#### Свойства + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
minPoint + Левый верхний угол прямоугольника.
maxPoint + Правый нижний угол прямоугольника.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
extend( + <Point> point ) + -Расширяет границы таким образом, чтобы в них входила переданная точка.
getCenter()PointВозвращает центральную точку прямоугольной области.
contains( + <Bounds> otherBounds ) + BooleanВозвращает true, если текущий прямоугольник содержит внутри себя переданный прямоугольник.
contains( + <Point> point ) + BooleanВозвращает true, если прямоугольник содержит внутри себя переданную точку.
intersects( + <Bounds> otherBounds ) + BooleanВозвращает true, если текущий прямоугольник пересекается с переданным прямоугольником.
isValid()BooleanВозвращает true, если если свойства границ инициализированы.
getSize()PointВозвращает размер прямоугольника.
diff --git a/src/doc/ru/manual/base-classes.md b/src/doc/ru/manual/base-classes.md new file mode 100644 index 000000000..5c7db5c7a --- /dev/null +++ b/src/doc/ru/manual/base-classes.md @@ -0,0 +1,172 @@ +## Базовые классы + +{toc} + +### Описание + +Служебный функционал, необходимый для работы API карт и разработки собственных модулей. + +### DG.Class + +`DG.Class` предоставляет возможность использовать ООП подход в разработке функционала API карт, и используется +для реализации большинства классов, приведенных в этой документации. + +Кроме реализации простой классической модели наследования имеются несколько свойств для удобной организации кода, +такие как `options`, `includes` и `statics`. + + var MyClass = DG.Class.extend({ + initialize: function (greeter) { + this.greeter = greeter; + // конструктор класса + }, + + greet: function (name) { + alert(this.greeter + ', ' + name) + } + }); + + // создает объект класса MyClass и передает "Hello" в конструктор + var a = new MyClass("Hello"); + + // вызывает метод greet, который показывает всплывающее окно с текстом "Hello, World" + a.greet("World"); + +#### Фабрики классов + +Объекты в API карт можно создавать без использования ключевого слова `new`. Это достигается путем дополнения +описания каждого класса статическим методом, имеющим наименование класса, только в нижнем регистре. + + new DG.Map('map'); + DG.map('map'); // эквивалентный вызов + +Подобные методы реализованы достаточно просто. Поэтому вы можете повторить поведение для своих классов. + + DG.map = function (id, options) { + return new DG.Map(id, options); + }; + +#### Наследование + +Для определения новых классов используется конструкция `DG.Class.extend`, также метод `extend` можно использовать +в любом другом классе, который наследуется от `DG.Class`: + + var MyChildClass = MyClass.extend({ + // ... новые свойства и методы + }); + +Данный код создаст класс, который унаследует все методы и свойства родительского класса (через цепочку прототипов), +при необходимости, добавляя или переопределяя родительские методы и свойства. Кроме того, корректно обрабатывается +оператор `instanceof`: + + var a = new MyChildClass(); + a instanceof MyChildClass; // true + a instanceof MyClass; // true + +Вы можете вызывать родительские методы (включая конструктор) из дочерних классов (так, как вы бы делали это с помощью +вызова `super` в других языках программирования) с помощью JavaScript функций `call` или `apply`: + + var MyChildClass = MyClass.extend({ + initialize: function () { + MyClass.prototype.initialize.call("Yo"); + }, + + greet: function (name) { + MyClass.prototype.greet.call(this, 'bro ' + name + '!'); + } + }); + + var a = new MyChildClass(); + a.greet('Jason'); // выведет "Yo, bro Jason!" + +#### Опции + +`options` — специальное свойство, которое в отличии от других объектов передаваемых через `extend` будет +объединено с аналогичным свойством родителя, вместо полного переопределени. Это позволяет управлять конфигурацией +объектов и значениями по умолчанию: + + var MyClass = DG.Class.extend({ + options: { + myOption1: 'foo', + myOption2: 'bar' + } + }); + + var MyChildClass = DG.Class.extend({ + options: { + myOption1: 'baz', + myOption3: 5 + } + }); + + var a = new MyChildClass(); + a.options.myOption1; // 'baz' + a.options.myOption2; // 'bar' + a.options.myOption3; // 5 + +Также имеется метод `DG.Util.setOptions`, который позволяет объединять опции, переданные в конструктор, с опциями, +заданными по умолчанию: + + var MyClass = DG.Class.extend({ + options: { + foo: 'bar', + bla: 5 + }, + + initialize: function (options) { + DG.Util.setOptions(this, options); + ... + } + }); + + var a = new MyClass({bla: 10}); + a.options; // {foo: 'bar', bla: 10} + +#### Включения + +`includes` — специальное свойство, которое подмешивает объекты в класс (такие объекты называются mixin-ами). + + var MyMixin = { + foo: function () { ... }, + bar: 5 + }; + + var MyClass = DG.Class.extend({ + includes: MyMixin + }); + + var a = new MyClass(); + a.foo(); + +Также вы можете подмешивать объекты в процессе выполнения программы с помощью метода `include`: + + MyClass.include(MyMixin); + +#### Статика + +`statics` — свойство, в котором описываются статические элементы класса. +Бывает удобно использовать для определения констант: + + var MyClass = DG.Class.extend({ + statics: { + FOO: 'bar', + BLA: 5 + } + }); + + MyClass.FOO; // 'bar' + +#### Хуки конструктора + +Если вы разрабатываете модуль к API, тогда велика вероятность того, что вам понадобится выполнить дополнительные +действия при инициализации объектов существующих классов (например, при инициализации объекта `DG.Polyline`). +Для подобного рода задач имеется метод `addInitHook`: + + MyClass.addInitHook(function () { + // ... выполнить дополнительные действия при вызове конструктора + // например, добавить обработчики событий, установить значения свойств и т.п. + }); + +Альтернативный вариант вызова, если необходимо использовать лишь один метод при инициализации: + + MyClass.addInitHook('methodName', arg1, arg2, …); + diff --git a/src/doc/ru/manual/basic-types.md b/src/doc/ru/manual/basic-types.md new file mode 100644 index 000000000..7619f5793 --- /dev/null +++ b/src/doc/ru/manual/basic-types.md @@ -0,0 +1,660 @@ +## Базовые типы данных + +{toc} + +### Описание + +В данном разделе описаны классы базовых типов данных, которые часто встречаются на страницах руководства API карт +и необходимы для работы с многими объектами карты. + +### DG.LatLng + +Географическая точка с определенной широтой и долготой. + + var latlng = DG.latLng(54.98, 82.89); + +Все методы, которые принимают объекты LatLng, также принимают широту и долготу в виде простого массива или объекта +(если не указано иное), то есть данные записи эквивалентны: + + map.panTo([54.98, 82.89]); + map.panTo({lon: 82.89, lat: 54.98}); + map.panTo({lat: 54.98, lng: 82.89}); + map.panTo(DG.latLng(54.98, 82.89)); + +#### Создание + + + + + + + + + + + + + + + + + + + + + + +
КонструкторОписание
DG.latLng( + <Number> latitude, + <Number> longitude, + <Number> altitude? ) + Создает объект, представляющий географическую точку с определенной широтой и долготой + (и опционально высотой).
DG.latLng( + <Array> coords ) + Ожидает массив вида [Number, Number] или [Number, Number, Number] + в качестве аргумента.
DG.latLng( + <Object> coords ) + Ожидает объект вида {lat: Number, lng: Number} или + {lat: Number, lng: Number, alt: Number} в качестве аргумента.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
equals( + <LatLng> otherLatLng, + <Number> maxMargin? ) + BooleanВозвращает true, если переданная широта и долгота находится в той же позиции + (с небольшой погрешностью). Погрешность, используемую по умолчанию, можно изменить + передав аргумент maxMargin.
toString()StringВозвращает строковое представление позиции (удобно при отладке).
distanceTo( + <LatLng> otherLatLng ) + NumberВозвращает расстояние (в метрах) до переданной широты и долготы, рассчитанное по + формуле Haversine.
wrap()LatLng

Возвращает новый объект LatLng, в котором долгота нормализуется + в диапазон от -180 до 180 градусов.

toBounds( + <Number> sizeInMeters ) + LatLngBounds

Возвращает новый объект LatLngBounds в котором + каждая из границ отстоит от указанной точки на sizeInMeters метров.

+ +#### Свойства + + + + + + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
latNumberШирота в градусах.
lngNumberДолгота в градусах.
altNumberВысота в метрах (опционально).
+ +### DG.LatLngBounds + +Описывает прямоугольную географическую область на карте. + + var southWest = DG.latLng(54.9801, 82.8974), + northEast = DG.latLng(54.9901, 82.9074), + bounds = DG.latLngBounds(southWest, northEast); + +Все методы, которые принимают объекты LatLngBounds также принимают их в виде простого массива +(если не указано иное), то есть границы могут быть указаны, как в этом примере: + + map.fitBounds([ + [54.9801, 82.8974], + [54.9901, 82.9074] + ]); + +#### Создание + + + + + + + + + + + + + + + + + + +
КонструкторОписание
DG.latLngBounds( + <LatLng> southWest, + <LatLng> northEast ) + Создает объект LatLngBounds, определяя юго-западный и северо-восточный углы прямоугольника.
DG.latLngBounds( + <LatLng[]> latlngs) + Создает объект LatLngBounds на основе географических точек, + которые находятся внутри описываемой области. Удобно использовать, если необходимо подстроить центр + и масштаб карты с помощью метода fitBounds.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
extend( + <LatLng> latlng ) + thisРасширяет область таким образом, чтобы в них входила переданная точка.
extend( + <LatLngBounds> otherBounds ) + thisРасширяет область таким образом, чтобы в них входили переданные границы другой области.
pad( + <Number> bufferRatio ) + LatLngBoundsВозвращает бОльшую область, увеличенную на заданный процент в каждом из направлений.
getCenter()LatLngВозвращает центральную точку области.
getSouthWest()LatLngВозвращает крайнюю юго-западную точку области.
getNorthEast()LatLngВозвращает крайнюю северо-восточную точку области.
getNorthWest()LatLngВозвращает крайнюю северо-западную точку области.
getSouthEast()LatLngВозвращает крайнюю юго-восточную точку области.
getWest()NumberВозвращает западную границу (долготу) области.
getSouth()NumberВозвращает южную границу (широту) области.
getEast()NumberВозвращает восточную границу (долготу) области.
getNorth()NumberВозвращает северную границу (широту) области.
contains( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если область содержит переданные границы.
contains( + <LatLng> latlng ) + BooleanВозвращает true, если область содержит переданную точку.
intersects( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если границы области пересекают переданные границы хотя бы в одной точке.
overlaps( + <Bounds> otherBounds ) + BooleanВозвращает true, если границы области перекрывают переданные границы в некотором пространстве.
toBBoxString()StringВозвращает строку с координатами границ в формате 'southwest_lng,southwest_lat,northeast_lng,northeast_lat'. + Удобно использовать для отправки запросов к веб-сервисам, возвращающим геоданные.
equals( + <LatLngBounds> otherBounds ) + BooleanВозвращает true, если координаты прямоугольной области эквивалентны переданным + (с небольшой погрешностью).
isValid()BooleanВозвращает true, если свойства объекта (данные границ) инициализированы должным образом.
+ +### DG.Point + +Точка с пиксельными координатами x и y. + + var point = DG.point(200, 300); + +Все методы, которые принимают объекты Point, также принимают +координаты в виде простого массива (если не указано иное), то есть данные записи эквивалентны: + + map.panBy([200, 300]); + map.panBy(DG.point(200, 300)); + +#### Создание + + + + + + + + + + + + + + + + + + +
КонструкторОписание
DG.point( + <Number> x, + <Number> y, + <Boolean> round? ) + Создает объект Point с заданными координатами x и y, при необходимости + округляя значения (если round установлен в true).
DG.point( + <Number[]> coords) + Ожидает массив вида [x, y].
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
clone()PointВозвращает копию оригинального объекта.
add( + <Point> otherPoint ) + PointВозвращает результат сложения координат заданной точки и текущей.
subtract( + <Point> otherPoint ) + PointВозвращает результат вычитания координат заданной точки из текущей.
divideBy( + <Number> num ) + PointВозвращает результат деления координат текущей точки на произвольное число.
multiplyBy( + <Number> num ) + PointВозвращает результат умножения координат текущей точки на произвольное число.
scaleBy( + <Point> scale ) + PointВозвращает новую точку, каждая координата которой получена умножением на соответствующую координату + scale. В терминах линейной алгебры, данная операция производит умножение на + матрицу масштабирования, + заданную scale.
unscaleBy( + <Point> scale ) + PointОбратная операция, относительно scaleBy.
round()PointВозвращает копию оригинального объекта с округленными координатами.
floor()PointВозвращает копию оригинального объекта с координатами, округленными вниз.
ceil()PointВозвращает копию оригинального объекта с координатами, округленными вверх.
distanceTo( + <Point> otherPoint ) + NumberВозвращает декартово расстояние между текущй и заданной точками.
equals( + <Point> otherPoint ) + BooleanВозвращает true, если заданная точка имеет аналогичные координаты.
contains( + <Point> otherPoint ) + BooleanВозвращает true, если обе координаты заданной точки меньше (в абсолютных величинах) координат + текущей точки.
toString()StringВозвращает строковое представление точки (удобно для отладки).
+ +#### Свойства + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
xNumberКоордината x.
yNumberКоордината y.
+ +### DG.Bounds + +Описывает прямоугольную область на карте в пиксельных координатах. + + var p1 = DG.point(10, 10), + p2 = DG.point(40, 60), + bounds = DG.bounds(p1, p2); + +Все методы, которые принимают объекты Point также принимают их в виде простого массива +(если не указано иное), то есть границы могут быть указаны, как в этом примере: + + otherBounds.intersects([[10, 10], [40, 60]]); + +#### Создание + + + + + + + + + + + + + + + + + + +
КонструкторОписание
DG.bounds( + <Point> topLeft, + <Point> bottomRight ) + Создает объект Bounds на основе переданных координат (обычно, координат левого-верхнего и правого-нижнего углов).
DG.bounds( + <Point[]> points ) + Создает объект Bounds на основе массива координат переданных точек.
+ +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
extend( + <Point> point ) + thisРасширяет область таким образом, чтобы в них входила переданная точка.
getCenter( + <Boolean> round? ) + PointВозвращает центральную точку области.
getBottomLeft()PointВозвращает координаты левого-нижнего угла области.
getTopRight()PointВозвращает координаты правого-верхнего угла области.
getSize()PointВозвращает размер области.
contains( + <Bounds> otherBounds ) + BooleanВозвращает true, если область содержит переданные границы.
contains( + <Point> point ) + BooleanВозвращает true, если область содержит переданную точку.
intersects( + <Bounds> otherBounds ) + BooleanВозвращает true, если границы области пересекают переданные границы хотя бы в одной точке.
overlaps( + <Bounds> otherBounds ) + BooleanВозвращает true, если границы области перекрывают переданные границы в некотором пространстве.
+ +#### Свойства + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
minPointЛевый верхний угол прямоугольной области.
maxPointПравый нижний угол прямоугольной области.
diff --git a/src/doc/ru/manual/utils.md b/src/doc/ru/manual/utils.md new file mode 100644 index 000000000..852f76b23 --- /dev/null +++ b/src/doc/ru/manual/utils.md @@ -0,0 +1,476 @@ +## Вспомогательные классы + +{toc} + +### DG.Browser + +Объект со статическими свойствами, описывающими браузер пользователя, например: + + if (DG.Browser.ie6) { + alert('Вам срочно нужно обновить свой браузер!'); + } + +#### Свойства + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
ieBooleantrue для всех версий Internet Explorer (не Edge).
ielt9Booleantrue для всех версий Internet Explorer ниже версии 9.
edgeBooleantrue для браузера Edge.
webkitBooleantrue для браузеров на основе WebKit, таких как Chrome и Safari (включая мобильные версии).
geckoBooleantrue для браузеров на основе gecko, таких как Firefox.
androidBooleantrue для мобильных браузеров работающих на базе платформы Android.
android23Booleantrue для мобильных браузеров на старых версиях Android устройств (2 и 3).
chromeBooleantrue для браузера Chrome.
safariBooleantrue для браузера Safari.
ie3dBooleantrue для всех версий Internet Explorer, поддерживающих CSS transform.
webkit3dBooleantrue для всех браузеров на основе WebKit, поддерживающих CSS transform.
gecko3dBooleantrue для всех браузеров на основе gecko, поддерживающих CSS transform.
opera12Booleantrue для всех версий Opera, поддерживающих CSS transform (версия 12+).
any3dBooleantrue для всех браузеров, поддерживающих CSS transform.
mobileBooleantrue для браузеров, работающих на современных мобильных устройствах.
mobileWebkitBooleantrue для мобильных браузеров на основе WebKit.
mobileWebkit3dBooleantrue для мобильных браузеров на основе WebKit, поддерживающих CSS transform.
mobileOperaBooleantrue для мобильной версии Opera.
mobileGeckoBooleantrue для мобильных браузеров на основе gecko.
touchBooleantrue для всех браузеров, поддерживающих touch events.
msPointerBooleantrue для браузеров, поддерживающих touch events модель от Microsoft (например, IE10).
pointerBooleantrue для всех браузеров, поддерживающих pointer events.
retinaBooleantrue для браузеров, работающих на устройствах с Retina экраном.
canvasBooleantrue для браузеров, поддерживающих <canvas>.
vmlBooleantrue для браузеров, поддерживающих VML.
svgBooleantrue для браузеров, поддерживающих SVG.
+ +### DG.Util + +Общие служебные методы и свойства. + +#### Методы + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
extend( + <Object> dest, + <Object> src? ) + ObjectОбъединяет свойства объекта src (или нескольких объектов) и свойства объекта + dest и возвращает последний. Также доступен под псевдонимом DG.extend.
create( + <Object> proto, + <Object> properties? ) + ObjectPolyfill для Object.create
bind( + <Function> fn, … ) + FunctionВозвращает функцию, которая выполняет функцию fn с определенным объектом контекста + obj (так, чтобы ключевое слово this внутри функции указывало на + obj). Также доступно под псевдонимом DG.bind.
stamp( + <Object> obj ) + NumberВозвращает уникальный ID объекта, создавая его при необходимости. Полезно для получения быстрого + доступа к объекту, находящемуся в группе.
throttle( + <Function> fn, + <Number> time, + <Object> context ) + FunctionВозвращает обертку над функцией fn, которая гарантирует, что функция не будет + вызвана чаще, чем раз в указанный интервал времени time (например, используется + при запросах к тайлам во время перетаскивания карты), опционально можно передать контекст + (context), с которым будет вызываться функция.
wrapNum( + <Number> num, + <Number[]> range, + <Boolean> includeMax? ) + NumberВозвращает число num приведенное к диапазону range (modulo). + Получившееся значение будет всегда меньше range[1], если только опция + includeMax не выставлена в true.
falseFn()FunctionВозвращает функцию, вызов которой всегда будет давать результат false.
formatNum( + <Number> num, + <Number> digits? ) + NumberВозвращает число num, округленное до digits десятичных знаков + (5 знаков по умолчанию).
trim( + <String> str ) + StringPolyfill для String.prototype.trim
splitWords( + <String> str ) + String[]Обрезает и разделяет строку на части, используя в качестве разделителя пробел, возвращает массив с этими частями.
setOptions( + <Object: options: Object> obj ) + ObjectОбъединяет свойства options со свойствами объекта obj, возвращаяя + получившийся объект. See Class options. Также доступен под псевдонимом DG.setOptions.
getParamString( + <Object> obj, + <String> existingUrl?, + <Boolean> uppercase? ) + StringПреобразует объект в URL-строку, например, {a: "foo", b: "bar"} + будет преобразован в '?a=foo&b=bar'. Если задан параметр existingUrl + результирующая строка будет добавлена в конец строки из параметра. Также возможно приведение названий + свойств к верхнему регистру (параметр uppercase). Простейший шаблонизатор также воспринимает + строки в формате 'Hello {a}, {b}' и объект вида {a: 'foo', b: 'bar'}. + При таком вызове метод возвращает строку ('Hello foo, bar').
isArray(obj)BooleanPolyfill для Array.isArray
indexOf()NumberPolyfill для Array.prototype.indexOf
requestAnimFrame( + <Function> fn, + <Object> context?, + <Boolean> immediate? ) + requestId: NumberИспользует планировщик для вызова функции fn при событии обновлении окна браузера (repaint). + Функция fn вызывается с контекстом context, если он задан. Когда задан параметр + immediate, fn функция вызывается сразу-же, если браузер не поддерживает нативно + window.requestAnimationFrame, + в противном случае вызов откладывается, до возникновения события перерисовки. Возвращает id, который может + быть использован для отмены задания для планировщика.
cancelAnimFrame( + <Number> id ) + Cancels a previous requestAnimFrame. See also window.cancelAnimationFrame.
+ +#### Свойства + + + + + + + + + + + + + + + + + + + +
СвойствоТипОписание
lastId + NumberПоследний уникальный ID, используемый stamp()
emptyImageUrl + StringURI, содержащий пустое GIF изображение, закодированное в base64. Используется для освобождения памяти + неиспользуемых картинок в мобильных WebKit браузерах (память освобождается установкой свойства + src в данное значение).
+ +### DG.Locale + +Функционал, с помощью которого осуществляется перевод пользовательского интерфейса. + +Подмешивает в карту два метода: setLang и +getLang. Также имеется объект DG.Locale, который можно подмешать +в любой внешний модуль, после чего в нем появится метод t, +с помощью которого можно осуществить перевод. Классы модулей, к которым примешивается DG.Locale должны +содержать внутри себя свойство `_map` и статическое свойство `Dictionary`. + +Базовым для всех словарей является словарь `DG.Dictionary`, в котором хранятся правила перевода слов во +множественные формы (plural rules). При создании модуля, использующего свои словари, необходимо их разместить +в папке lang. К примеру, если вы будете использовать итальянский и русский языки, тогда необходимо создать +файлы lang/it.js и lang/ru.js. Примеры создания словарей рассмотрены ниже. + +#### Пример использования +Подмешивание (mixin) функционала локализации в модуль: + + DG.LocaleExample = DG.Control.extend({ + includes: DG.Locale, + statics: { + Dictionary: {} + } + ... + } + +Подписка на событие langchange: + + this._map.on('langchange', this._updateText, this); + +Перевод строки на текущий язык карты: + + container.innerHTML = this.t("{n} people", 16700000) + ' ' + this.t("regularly use 2GIS"); + +Создание собственных словарей на итальянском и русском языках: + +Cодержимое файла lang/it.js: + + DG.LocaleExample.Dictionary.it = DG.extend({ + "{n} people" : ["{n} utente", "{n} utenti"], + "regularly use 2GIS" : "utilizzano regolarmente 2GIS" + }, DG.Dictionary.it); + +Cодержимое файла lang/ru.js: + + DG.LocaleExample.Dictionary.ru = DG.extend({ + "{n} people" : ["{n} пользователь", "{n} пользователя", "{n} пользователей"], + "regularly use 2GIS" : "регулярно используют 2GIS" + }, DG.Dictionary.ru); + +### DG.LineUtil + +Набор методов для обработки ломаных. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
simplify( + <Point[]> points, + <Number> tolerance ) + Point[]Уменьшает количество точек в ломаной и возвращает новую упрощенную ломаную. Позволяет увеличить + производительность обработки/отображения ломаных на карте. Параметр tolerance влияет + на величину упрощения (чем меньше значение, тем лучше качество геометрии и ниже производительность).
pointToSegmentDistance( + <Point> p, + <Point> p1, + <Point> p2 ) + NumberВозвращает расстояние между точкой p и сегментом между точками p1 и p2.
closestPointOnSegment( + <Point> p, + <Point> p1, + <Point> p2 ) + NumberВозвращает ближайшую точку на сегменте p1 p2 до точки p.
+ +### DG.PolyUtil + +Набор методов для обработки геометрии многоугольников. + + + + + + + + + + + + + + + + + +
МетодВозвращаетОписание
clipPolygon( + <Point[]> points, + <Bounds> bounds, + <Boolean> round? ) + Point[]Обрезает многоугольник, заданный координатами points по заданным границам + (используя алгоритм Sutherland-Hodgemanа).