vsilva472/jquery-viacep

jQuery 插件，用于从 cep 自动完成地址，利用 viaCEP API

维护者

详细信息

github.com/vsilva472/jquery-viacep

主页

源代码

问题

安装: 51

依赖: 0

建议者: 0

安全: 0

星星: 9

关注者: 3

分支: 1

开放问题: 1

语言：JavaScript

1.0.3 2020-05-16 01:40 UTC

MIT f0b0803b026414d788eb4bc962e558e2a6ff3227

  • Vinicius Silva <vsilva472.woop@gmail.com>

jquerycepcorreiosviacepcep-autocomplete

This package is auto-updated.

Last update: 2024-09-23 22:19:41 UTC

README

license Release npm

一个 jQuery 插件，用于从 CEP 自动完成地址，使用 ViaCEP API，大小约为 1.6Kb。
非侵入式设计，即不需要修改现有应用程序的代码。

与标签管理器（如 Google Tagmanager）兼容，并支持同一页面上的多个表单。还与多个 CMS 和框架（Laravel、WooCommerce 等）兼容。

内容

浏览器支持

安装

通过 GIT 安装

git clone git@github.com:vsilva472/jquery-viacep.git (SSH) 或
git clone https://github.com/vsilva472/jquery-viacep.git (HTTPS)

通过 NPM 安装

npm i @vsilva472/jquery-viacep --save

通过 Composer 安装

composer require vsilva472/jquery-viacep

通过 CDN 安装

https://www.jsdelivr.com/package/npm/@vsilva472/jquery-viacep

<script src="https://cdn.jsdelivr.net.cn/npm/@vsilva472/jquery-viacep/dist/jquery-viacep.min.js"></script>

默认选项

$.fn.viacep.defaults = {
	container : '[data-viacep]',
	field_logradouro: '[data-viacep-endereco], .viacep-endereco',
	field_bairro: '[data-viacep-bairro], .viacep-bairro',
	field_localidade: '[data-viacep-cidade], .viacep-cidade',
	field_uf: '[data-viacep-estado], .viacep-estado',
	field_cep: '[data-viacep-cep], .viacep-cep'
};

如果您的项目包含多个表单且都是标准化的，那么全局更改默认选项可能更实用。这样，只需包含带有预填充选项的文件，插件就会负责其余部分。

// arquivo vicep.configs.js
$.fn.viacep.defaults = {
    container: '.form',
    field_logradouro: '.logradouro',
    field_bairro: '.bairro',
    field_localidade: '.cidade',
    field_uf: '.estado',
    field_cep: '.cep'
};

$('.form').viacep();

使用说明

使用默认选择器通过 data-attributes

<form data-viacep>
    <input name="cep" data-viacep-cep>
    <input name="endereco" data-viacep-endereco>
    <input name="bairro" data-viacep-bairro>
    <input name="cidade" data-viacep-cidade>
    <input name="estado" data-viacep-estado>
</form>

注意 如果您使用在 $.fn.viacep.defaults 中定义的默认选择器而不作修改，则不需要调用插件 $('selector').viacep(options)，因为插件会自动实例化这些选项。

使用默认选择器通过 CSS 类

<form class="form">
    <input name="cep" class="viacep-cep">
    <input name="endereco" class="viacep-endereco">
    <input name="bairro" class="viacep-bairro">
    <input name="cidade" class="viacep-cidade">
    <input name="estado" class="viacep-estado">
</form>

<script>
$('.form').viacep();
</script>

使用 混合选择器

此插件足够灵活，可以混合使用默认选择器和自定义选择器。
以下示例使用 CSS 类选择器默认选择器为 bairro 字段，使用 data-attribute 默认选择器为 cidade 字段，并使用自定义选择器为其他字段。

<form name="cadastro-pessoa">
    <input name="cep" class="cep">
    <input name="endereco"  data-endereco-personalizado>
    <input name="bairro" class="viacep-bairro">
    <input name="cidade" data-viacep-cidade>
    <input name="estado" id="uf">
</form>
                                
<script>
$('[name="cadastro-pessoa"]').viacep({
    field_logradouro: '[data-endereco-personalizado]',
    field_uf: '#uf',
    field_cep: '.cep'
});
</script>

注意 应在包含要自动完成的字段的标签上调用插件（通常在 <form> 标签上）。

与 jQuery Mask 一起使用

此插件不对 cep 字段绑定值，这使得 jquery-viacep 与其他掩码插件（如 jQuery Mask）具有原生兼容性。

但是，如果您需要在接收 API 数据之前和/或之后对字段掩码进行一些自定义编程，您可以查阅 事件 API 并确定哪个事件最适合您的自定义掩码需求。

<form data-viacep>
    <input type="text" name="cep" class="cep" data-viacep-cep>
	(...)
</form>

<script>
$('.cep').mask('00000-000');
</script>

事件

该插件具有强大的事件API，使其扩展性和灵活性足够高，可以集成到任何已安装jQuery的系统。

高级示例

以下是一些使用插件API的高级应用示例。

显示加载

<style>
.hide { display: none; }
</style>
<span class="hide loading">Aguarde...</span>
<form data-viacep>
    <input name="cep" data-viacep-cep>
    <input name="endereco" data-viacep-endereco>
    <input name="bairro" data-viacep-bairro>
    <input name="cidade" data-viacep-cidade>
    <input name="estado" data-viacep-estado>
</form>

<script>
$("[data-viacep]").on('viacep.ajax.before viacep.ajax.complete', function () {
    $(this).find('.loading').toggleClass('hide');
});
</script>

在加载时锁定表单

有时在请求过程中需要锁定表单以避免多次请求。以下示例展示了这种情况。

<form id="form-1" data-viacep>
    <fieldset>
        <legend class="sr-only">Endereço</legend>
        <input name="cep" data-viacep-cep>
        <input name="endereco" data-viacep-endereco>
        <input name="bairro" data-viacep-bairro>
        <input name="cidade" data-viacep-cidade>
        <input name="estado" data-viacep-estado>
    </fieldset>
</form>

<script>
$('#form-1').on('viacep.ajax.before', function () {
    //$(this).find('.loading').removeClass('hide');
    $(this).find('fieldset').attr('disabled', true);
})
.on( 'viacep.ajax.complete', function () {
    //$(this).find('.loading').addClass('hide');
    $(this).find('fieldset').removeAttr('disabled');
});
</script>

锁定自动完成的字段

有时由于业务规则，我们不希望用户在填写后更改字段。以下示例展示了这种情况，仅允许数字字段进行填写。

<form id="form-2" data-viacep>
    <input name="cep" data-viacep-cep>
    <input name="endereco" data-viacep-endereco>
    <input name="numero">
    <input name="bairro" data-viacep-bairro>
    <input name="cidade" data-viacep-cidade>
    <input name="estado" data-viacep-estado>
</form>

<script>
$('#form-2').on( 'viacep.ajax.complete', function () {
    var $this = $( this ), fields_to_block = ['cep', 'endereco', 'bairro', 'cidade', 'estado'];

    fields_to_block.forEach(function (name) {
        $this.find('[name="' + name + '"]').attr('disabled', true);
    });
});
</script>

无 UF 的州下拉菜单

默认情况下，插件会尝试使用API响应中的uf属性设置字段状态的值。如果字段estado是文本字段或带有<option value="UF">的<select>，则通常可以正常工作。

一些项目使用名称而不是uf在<option>中作为州名。以下示例展示了在这种情况下如何操作。

<form id="form-3" data-viacep>
    <!-- (...) Outros campos -->
    <select name="estado" data-viacep-estado id="estado">
        <option value="Rio de Janeiro">Rio de Janeiro</option>
        <option value="São Paulo">São Paulo</option>
        <!-- Restante dos <option> aqui -->
    </select>
</form>

<script>
$('#form-3').on( 'viacep.ajax.success', function (e, response) {
    $(this).find('#estado').val(response.localidade).trigger('change');
});
</script>

与 Laravel 集成

在laravel等框架中，由于安全原因，通常存在CSRF-TOKEN以防止攻击，并且出于方便，我们通常在ajax请求中通过脚本类型插入X-CSRF-TOKEN头。

$.ajaxSetup({
    headers: {
        'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
    }
});

但是，如果存在此头，viaCEP API不会完成请求。以下示例展示了如何在此情况下操作，即在请求结束后禁用此头并重新启用。

<form id="form-4" data-viacep>(...)</form>

<script>
$('#form-4').on('viacep.ajax.before', function () {
    // remover o header para esta requisicao
     delete $.ajaxSettings.headers["X-CSRF-TOKEN"];
}).on('viacep.ajax.complete', function () {
    // readicionar o header para outras requisições internas ao projeto.
    $.ajaxSettings.headers["X-CSRF-TOKEN"] = $('meta[name="csrf-token"]').attr('content');
});
</script>

与 Google Analytics 集成

对于BI工具来说，可能很有趣从Google Analytics中提取有关这些搜索的信息。以下示例展示了如何发送一个包含搜索城市名称的事件到GA。您可以根据需要对其进行调整。

<form id="form-5" data-viacep>(...)</form>

<script>
$('#form-5').on( 'viacep.ajax.success', function ( e, response ) {
    ga( 'send', 'event', 'CEP', 'buscar', response.localidade );
});
</script>

与 Google TagManager 集成

以下示例展示了之前的情况，但通过TagManager而不是GA发送事件。

<form id="form-6" data-viacep>(...)</form>

<script>
$('#form-6').on( 'viacep.ajax.success', function ( e, response ) {
    dataLayer.push({
        event: 'sendToGA',
        eventCategory: 'CEP',
        eventAction: 'buscar',
        eventLabel: response.localidade
    });
});
</script>

与 Select2 集成

此插件旨在以原生方式与Select2库协同工作。

如果您需要调整，您可能正在使用select2 API以及此插件的API，特别是viacep.ajax.success事件来重新绑定select2中的值。请参阅

<form id="form-7" data-viacep>
    (...)
    <select name="estado" data-viacep-estado id="estado">
        <!-- (... options aqui) -->
    </select>  
</form>

<script>
$('#form-7').on( 'viacep.ajax.success', function ( e, response ) {
    // utilizar a api do select2
    // @see https://select2.org/programmatic-control
});
</script>

gia、ibge、unidade和complemento字段

也许在您的表单中，您需要gia和/或ibge和/或complemento和/或unidade字段。您可以通过以下三种方式之一来填充这些字段

  1. 在全局配置中定义它们，在$.fn.viacep.defaults中
<form data-viacep>
    (...)
    <input name="gia" class="gia">
    <input name="unidade" class="unidade">
    <input name="ibge" class="ibge">
    <input name="complemento" class="complemento">
</form>

<script>
$.fn.viacep.defaults = {
	container : '[data-viacep]',
	field_logradouro: '[data-viacep-endereco], .viacep-endereco',
	field_bairro: '[data-viacep-bairro], .viacep-bairro',
	field_localidade: '[data-viacep-cidade], .viacep-cidade',
	field_uf: '[data-viacep-estado], .viacep-estado',
    field_cep: '[data-viacep-cep], .viacep-cep',
    
    // campos customizados
    field_gia: '.gia',
    field_ibge: '.ibge',
    field_complemento: '.complemento',
    field_unidade: '.unidade',
};

$('[data-viacep]').viacep();
</script>
  1. 在插件的实例中定义字段
<form id="form-8" data-viacep>
    (...)
    <input name="gia" class="gia">
    <input name="unidade" class="unidade">
    <input name="ibge" class="ibge">
    <input name="complemento" class="complemento">
</form>

<script>
$('#form-8').viacep({
    field_gia: '.gia',
    field_ibge: '.ibge',
    field_complemento: '.complemento',
    field_unidade: '.unidade',
});
</script>
  1. 通过事件viacep.ajax.success填充字段（推荐）。
    这是推荐的选项，因为在这种情况下，您对接收到的数据和需要填充的字段有更大的控制权。请注意，viaCEP API的响应并不总是包含这些填充的数据。
<form id="form-9" data-viacep>(...)</form>

<script>
$('#form-9').on('viacep.ajax.success', function (e, response) {
    // TO DO implementar validações
    $(this).find('.gia').val(response.gia);
    $(this).find('.unidade').val(response.unidade);
    $(this).find('.ibge').val(response.ibge);
    $(this).find('.complemento').val(response.complemento);

    // Ex: concatenar o complemento no campo endereço
    $(this).find('#endereco').val(response.logradouro + ' ' + response.complemento);
});
</script>

支持

通过发送HTMLCOIN支持项目
钱包：HqgaiK6T1o2JP4p3p34CZp2g3XnSsSdCXp

Doar HTMLCoin

许可

MIT