Skip to content

garakh/kladrapi-jsclient

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Это устаревший плагин. Используйте новый https://github.com/fias-api/jquery

jQuery Kladr

Плагин для автодополнения полей адреса при вводе.
В качестве источника данных используется сервис [kladr-api.ru] 1.

Архитектура

  • $.kladr - ( статичный объект ) предоставляет методы и свойства для работы с сервисом.
  • $('input').kladr - ( плагин jQuery ) плагин для автодополнения адреса.
  • $('input').kladrZip - ( плагин jQuery ) плагин для полей с почтовым индексом.

Свойства объекта $.kladr

  • url - url сервиса, по умолчанию [http://kladr-api.ru/api.php] 2.
  • type - перечисление используемых типов объектов. Список значений: region (область, регион), district (район), city (населённый пункт), street (улица), building (строение).
  • typeCode - перечисление используемых типов населённых пунктов. Список значений: city (город), settlement (посёлок), village (деревня, село).
  • validate = function (query) {} - выполняет проверку корректности объекта запроса.
  • api = function (query, callback) {} - непосредственно выполняет запрос к сервису. В качестве параметров принимает объект запроса и функцию, которой будет передан ответ сервиса.
  • check = function (query, callback) {} - проверяет существование объекта. В качестве параметров принимает объект запроса и функцию, которой будет передан объект (если он существует) либо false.
  • setValues = function (values, selector) {} - устанавливает значения для полей, к которым подключён плагин $('input').kladr. В качестве параметра values принимает массив объектов КЛАДР или объект вида {'тип объекта' => название или id объекта}. Второй параметр аналогичен параметру функции getInputs.
  • setDefault = function (param1, param2) {} - устанавливает значения по умолчанию для параметров плагина $('input').kladr. В качестве параметров принимает аналогично плагину либо объект со списком изменяемых параметров, либо пару "параметр - новое значение параметра".
  • getDefault = function (param) {} - возвращает значение по умолчанию для параметра плагина $('input').kladr. В качестве параметра принимает название параметра плагина.
  • getInputs = function (selector) {} - возвращает jQuery коллекцию полей ввода, к которым был подключён плагин $('input').kladr. В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей, по умолчанию body.
  • buildAddress = function (objs) {} - строит строку адреса на основании массива объектов КЛАДР.
  • getAddress = function (selector, build) {} - возвращает строку адреса на основании полей ввода, к которым был подключён плагин $('input').kladr. Первый параметр аналогичен параметру функции getInputs. В качестве второго параметра принимает функцию, которой будет собираться строка адреса, по умолчанию buildAddress.

Параметры плагина $('input').kladr

  • token - токен для доступа к сервису, по умолчанию null.
  • key - ключ для доступа к сервису, по умолчанию null.
  • type - тип подставляемых объектов, по умолчанию null.
  • typeCode - тип подставляемых населённых пунктов, по умолчанию null. Может быть использован только если type == 'city'.
  • parentType - тип родительского объекта, по умолчанию null.
  • parentId - идентификатор родительского объекта, по умолчанию null.
  • limit - количество отображаемых в выпадающем списке объектов, по умолчанию 10.
  • oneString - включить ввод адреса одной строкой, по умолчанию false.
  • withParents - получить объект вместе с родителями, по умолчанию false.
  • parentInput - селектор, DOM элемент или же объект jQuery, в котором находится поле ввода родительского объекта, по умолчанию null.
  • verify - проверять введённые данные, по умолчанию false.
  • spinner - отображать ajax-крутилку, по умолчанию true.
  • current - текущий, выбранный объект КЛАДР, только для чтения.
  • controller - контроллер плагина, только для чтения.

Методы плагина $('input').kladr

  • source = function (query) { return objects; } - функция для получения списка объектов отображаемых при автодополнении. В качестве параметра принимает объекта запроса. По умолчанию запрашивает данные у сервиса [kladr-api.ru] 1. Может быть переопределена для получения объектов из другого источника.
  • labelFormat = function (obj, query) { return label; } - функция для форматирования значений в списке. В качестве параметров принимает obj – объект КЛАДР, query – объект запроса.
  • valueFormat = function (obj, query) { return label; } – функция для форматирования подставляемых в поле ввода значений. В качестве параметров принимает obj – объект КЛАДР, query – объект запроса.
  • showSpinner = function ($spinner) {} - функция, выводящая ajax-крутилку. В качестве параметра принимает jQuery объект ajax-крутилки.
  • hideSpinner = function ($spinner) {} - функция, скрывающая ajax-крутилку. В качестве параметра принимает jQuery объект ajax-крутилки.

События плагина $('input').kladr

Во все события в качестве контекста (this) передаётся текущее поле ввода.

В обработчиках событий ...Before (openBefore, closeBefore) объявленных как параметр плагина ( $('').kladr({openBefore: function () {}}) ) можно отменить действие плагина, если в функции вернуть false ( $('').kladr({openBefore: function () { return false; }}) ).

  • openBefore = function () {} - возникает перед открытием списка объектов. Доступно как событие kladr_open_before поля ввода.
  • open = function () {} - открыт список объектов. Доступно как событие kladr_open поля ввода.
  • closeBefore = function () {} - возникает перед закрытием списка объектов. Доступно как событие kladr_close_before поля ввода.
  • close = function () {} - закрыт список объектов. Доступно как событие kladr_close поля ввода.
  • sendBefore = function (query) {} - возникает перед отправкой запроса к сервису. В параметре передаётся объект запроса. Доступно как событие kladr_send_before поля ввода.
  • send = function () {} - отправлен запрос к сервису. Доступно как событие kladr_send поля ввода.
  • receive = function () {} - получен ответ от сервиса. Доступно как событие kladr_receive поля ввода.
  • selectBefore = function () {} - возникает перед изменением текущего объекта. Доступно как событие kladr_select_before поля ввода.
  • select = function (obj) {} - выбран объект в списке. В параметре передаётся текущий, выбранный объект КЛАДР. Доступно как событие kladr_select поля ввода.
  • checkBefore = function () {} - возникает перед проверкой введённых пользователем данных. Вызывается только если параметр verify = true. Доступно как событие kladr_check_before поля ввода.
  • check = function (obj) {} - проверен введённый пользователем объект. Вызывается только если параметр verify = true. В параметре передаётся текущий объект КЛАДР. Доступно как событие kladr_check поля ввода.
  • change = function (obj) {} - изменился текущий объект (current). В параметре передаётся текущий объект КЛАДР. Доступно как событие kladr_change поля ввода.

Методы контроллера плагина $('input').kladr

  • setValueByName = function (name) { return controller; } - устанавливает значение поля ввода. В качестве параметра принимает имя объекта.
  • setValueById = function (id) { return controller; } - устанавливает значение поля ввода. В качестве параметра принимает id объекта.
  • setValueByObject = function (obj) { return controller; } - устанавливает значение поля ввода. В качестве параметра принимает объект КЛАДР.
  • setValue = function (value) { return controller; } - устанавливает значение поля ввода. Если в качестве параметра передана строка, значение будет установлено методом setValueByName. Если передано число методом setValueById, если объект методом setValueByObject.
  • clear = function () { return controller; } - очищает поле ввода.

Пример использования контроллера можно посмотреть в папке [examples] 3.

Плагин $('input').kladrZip

Плагин $('selector').kladrZip выполняет проверку введённого пользователем почтового индекса. В случае если введённый индекс соответствует реальному адресу, плагин подставляет объекты этого адреса в другие поля формы (см. пример формы для ввода адреса в папке [examples] 3).

В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей адреса, по умолчанию body.

Структура папок, файлов

  • jquery.kladr.min.js - Минимифицированный код плагина
  • jquery.kladr.min.css - Минимифицированные стили
  • examples - Примеры
  • images - Изображения плагина
  • kladr - Исходный код плагина

Примеры

Автодополнение для ввода адреса одной строкой:

$('input').kladr({
	oneString: true
});

Автодополнение городами России:

$('input').kladr({
    type: $.kladr.type.city
});

Изменение подписи при выборе района:

$('input').kladr({
    type: $.kladr.type.district,
    select: function(obj){
        $('label').text(obj.type);
    }
});

Проверка вводимого пользователем почтового индекса

$('input').kladrZip('form');

Более подробные примеры можно найти в папке [examples] 3.

Загрузка

Загрузить последнюю версию плагина себе в проект можно с помощью Bower:

bower install jquery.kladr

Сборка своей версии плагина

Клонируем репозиторий плагина:

git clone git://github.com/garakh/kladrapi-jsclient.git

После внесения изменений, выполняем сборку плагина с помощью следующей команды:

npm run build

Лицензия

Решение распространяется под лицензией «Общественное достояние» (Public Domain) и может быть свободно используемо любым лицом без выплат авторских вознаграждений.