Plugin jQuery jVectorMap

Publicado em 08 de junho de 2011

Hoje vou mostrar um pouco sobre o plugin jVectorMap que pelo nome mesmo já matamos que é utilizado para mostrar mapas vetoriais e visualizar dados em páginas HTML. Ele usa SVG em todos os navegadores modernos como o Firefox 3 ou 4, Safari, Chrome, Opera, IE9, enquanto para as versões mais antigas do IE 6-8 é equipado com VML. Usar jVectorMap é bastante simples, como para qualquer outro plugin jQuery. Tudo que você precisa é conectar-se JavaScript e CSS do plugin:

<link href="jquery.vector-map.css" media="screen" rel="stylesheet" type="text/css" />
<script src="jquery.vector-map.js" type="text/javascript"></script>
<script src="world-en.js" type="text/javascript"></script>

E depois inicializá-lo da seguinte forma.

$(function(){
    $('#map').vectorMap();
});

Dessa forma, você pode obter o resultado como abaixo

Agora pode ainda fornecer vários parâmetros para a função de inicialização, personalizando a aparência e o comportamento do mapa. Você pode encontrar a descrição de todos os parâmetros disponíveis abaixo:

Parametros

Ao inicializar o mapa que você pode fornecer parâmetros para alterar sua aparência e estilo.

• color #ffffff
  Cor das regiões mapa.
• hoverColor black
  Cor da região quando o mouse está sobre ele.
• hoverOpacity
  Opacidade da região quando o mouse está sobre ele.
  
• backgroundColor #505050
  Cor de fundo do mapa em qualquer formato compatível com CSS.
• colors
  Cores das regiões individuais do mapa.Teclas de cores devem ser em letras minúsculas.
• scaleColors ['#b6d6ff', '#005ace']
  Esta opção define a cor com que as regiões vão ser pintadas quando você definir valores de opção. Array ScaleColors pode ter mais dois elementos. Elementos devem ser strings representando as cores em formato RGB hexadecimal.
• normalizeFunction 'linear'
  Esta função pode ser usada para melhorar os resultados de visualizações de dados com a natureza não-linear. Função recebe o valor bruto como o primeiro parâmetro e deve retornar o valor que será utilizado nos cálculos de cor, com o qual determinada região vão ser pintadas.
• onLabelShow
  Função callback que será chamado antes da label ser exibida. Label objeto DOM e o código do país será passado para o callback como argumentos.
• onRegionOver
  Função callback que será chamado quando o cursor do mouse entra na região do mapa. Código do país será passado para o callback como argumento.
• onRegionOut
  Função callback que será chamado quando o cursor do mouse sai da região do mapa. Código do país será passado para o callback como argumento.
• onRegionClick
  Função callback que será chamado quando o usuário clica na região do mapa. Código do país será passado para o callback como argumento.

Mudança das opções dinâmicas

A maioria das opções pode ser alterada após a inicialização usando o seguinte código:

$('#map').vectorMap('set', 'colors', {us: '#0000ff'});

Em vez de cores, pode ser usado em qualquer parâmetro, exceto callbacks. Callbacks podem ser adicionados e removidos usando padrão jQuery de trabalhar com eventos.

Eventos

Você pode definir a função callback quando você inicializa jVectorMap:

$('#map-events').vectorMap({
    onLabelShow: function(event, label, code){},
    onRegionOver: function(event, code){},
    onRegionOut: function(event, code){},
    onRegionClick: function(event, code){}
});

Ou, usando o mecanismo padrão jQuery:

$('#map-events').bind('labelShow.jvectormap', function(event, label, code){})
$('#map-events').bind('regionMouseOver.jvectormap', function(){event, code})
$('#map-events').bind('regionMouseOut.jvectormap', function(){event, code})
$('#map-events').bind('regionClick.jvectormap', function(){event, code})

Considere o fato de que você pode usar recursos standart de eventos jQuery() como event.preventDefault ou retornando FALSE do callback para evitar o comportamento padrão de jVectorMap (mostrando label ou mudando a cor do país em foco). No exemplo a seguir, quando o usuário move o cursor do mouse sobre o label do Canadá não será mostrado e a cor do país não será alterada. No mesmo label para a Rússia terá de texto personalizado

$('#map-events').vectorMap({
    onLabelShow: function(event, label, code){
        if (code == 'ca') {
            event.preventDefault();
        } else if (code == 'ru') {
            label.text('Bears, vodka, balalaika');
        }
    },
    onRegionOver: function(event, code){
        if (code == 'ca') {
            event.preventDefault();
        }
    },
});

Visualização de dados com jVectorMap

Aqui eu quero demonstrar como a visualização de alguns dados geográficos relacionados pode ser feito usando jVectorMap. Vamos visualizar informações sobre o PIB em 2010 para cada país. No início, nós precisamos de alguns dados.Não podemos ter informações em formato xsl, que pode ser convertido primeiro em csv e depois para json com qualquer linguagem de script. Agora temos de arquivo gdp-data.js com o conteúdo.

var gdpData = {"af":16.63,"al":11.58,"dz":158.97,...}

Código para visualização

var max = 0,
    min = Number.MAX_VALUE,
    cc,
    startColor = [200, 238, 255],
    endColor = [0, 100, 145],
    colors = {},
    hex;
//find maximum and minimum values
for (cc in gdpData) {
    if (parseFloat(gdpData[cc]) > max) {
        max = parseFloat(gdpData[cc]);
    }
    if (parseFloat(gdpData[cc]) < min) {
        min = parseFloat(gdpData[cc]);
    }
}
//cores definidas de acordo com os valores do GDP
for (cc in gdpData) {
    if (gdpData[cc] > 0) {
        colors[cc] = '#';
        for (var i = 0; i<3; i++) {
            hex = Math.round(startColor[i] + (endColor[i] - startColor[i])*(gdpData[cc] / (max - min))).toString(16);
            if (hex.length == 1) {
                hex = '0'+hex;
            }
            colors[cc] += (hex.length == 1 ? '0' : '') + hex;
        }
    }
}
//inicializando jVectorMap
$('#example-map-2').vectorMap({
    colors: colors,
    hoverOpacity: 0.7,
    hoverColor: false
});

Resultado

Realmente não é difícil. Mas temos dois problemas. No início é necessário escrever um código e também não ficou muito boa a visualização, porque a maioria dos países tem a mesma cor. Isso acontece porque a função linear foi usada para converter os valores para as cores, mas os dados raramente tem caráter linear. Então, nós precisamos usar alguma escala não-linear para visualizar os dados. Felizmente jVectorMap tem uma funcionalidade para resolver estes problemas, basta fornecer parâmetros adicionais a função de inicialização

$('#example-map-3').vectorMap({
    values: gdpData,
    scaleColors: ['#C8EEFF', '#006491'],
    normalizeFunction: 'polynomial',
    hoverOpacity: 0.7,
    hoverColor: false
});

Mapas

Dois mapas vetoriais adicionais estão disponíveis: EUA e Alemanha no pacote padrão.

$('#map-usa').vectorMap({map: 'usa_en'});

$('#map-germany').vectorMap({map: 'germany_en'});

Donwload jVectorMap aqui.

Versão original em inglês

Twitter: @jqmagazine