Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Pull request Compare This branch is 8 commits ahead, 1 commit behind garakh:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Refactoring Jun 11, 2019
images optimize images Oct 24, 2014
src Refactoring Jun 11, 2019
.gitignore Update Dec 13, 2018
README.md Refactoring Jun 11, 2019
bower.json Update Dec 13, 2018
gulpfile.js Refactoring Jun 11, 2019
jquery.fias.min.css Refactoring Jun 11, 2019
jquery.fias.min.js
package.json Update Dec 13, 2018

README.md

jQuery плагин для kladr-api.ru

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

Архитектура

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

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

  • url — url сервиса, по умолчанию [http://kladr-api.ru/api.php].
  • token — токен (для доступа к платным серверам)
  • timeout — таймаут для запросов (по умолчанию 3000)
  • 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').fias. В качестве параметра values принимает массив объектов КЛАДР или объект вида {'тип объекта' => название или id объекта}. Второй параметр аналогичен параметру функции getInputs.
  • setDefault = function (param1, param2) {} — устанавливает значения по умолчанию для параметров плагина $('input').fias. В качестве параметров принимает аналогично плагину либо объект со списком изменяемых параметров, либо пару "параметр - новое значение параметра".
  • getDefault = function (param) {} — возвращает значение по умолчанию для параметра плагина $('input').kladr. В качестве параметра принимает название параметра плагина.
  • getInputs = function (selector) {} — возвращает jQuery коллекцию полей ввода, к которым был подключён плагин $('input').fias. В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей, по умолчанию body.
  • buildAddress = function (objs) {} — строит строку адреса на основании массива объектов КЛАДР.
  • getAddress = function (selector, build) {} — возвращает строку адреса на основании полей ввода, к которым был подключён плагин $('input').fias. Первый параметр аналогичен параметру функции getInputs. В качестве второго параметра принимает функцию, которой будет собираться строка адреса, по умолчанию buildAddress.

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

  • token — токен для доступа к сервису. На бесплатном тарифе можно не указывать.
  • 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').fias

  • source = function (query) { return objects; } — функция для получения списка объектов отображаемых при автодополнении. В качестве параметра принимает объекта запроса. По умолчанию запрашивает данные у сервиса [kladr-api.ru] Может быть переопределена для получения объектов из другого источника.
  • 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').fias

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

В обработчиках событий ...Before (openBefore, closeBefore) объявленных как параметр плагина ( $('').fias({openBefore: function () {}}) ) можно отменить действие плагина, если в функции вернуть false ( $('').fias({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').fiasZip

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

Параметры:

$('selector').fiasZip(selector, onFoundCallback(obj));
  • selector — DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей адреса, по умолчанию body.
  • onFoundCallback(obj) — коллбек вызывается, когда по индексу найден адрес. obj — объект с адресом

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

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

Примеры

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

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

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

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

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

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

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

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

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

Лицензия

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

You can’t perform that action at this time.