Para melhorar a integração de nossos widgets AQI em sites externos, desenvolvemos um novo feed de API de widget. Comparado ao feed de widget existente, este novo feed de API oferece muito mais flexibilidade para a integração, mas também muito mais opções para personalizar a aparência do widget.
 | 159 | |
 | 77 | |
 | 51 |
Você pode, por exemplo, exibir um pequeno widget tão simples como Beijing
A nova estrutura também suporta modelos, vários idiomas (inglês, chinês simplificado e tradicional, espanhol, ...), bem como a possibilidade de fazer integração programática com retornos de chamada javascript baseados em dados.
A. Configuração básica
A integração básica é simples e direta. Primeiro você precisa adicionar o seguinte trecho de código:
<script type="text/javascript" charset="utf-8"> (function (w, d, t, f) { w[f] = w[f] || function (c, k, n) { s = w[f], k = s['k'] = (s['k'] || (k ? ('&k=' + k) : '')); s['c'] = c = (c instanceof Array) ? c : [c]; s['n'] = n = n || 0; L = d.createElement(t), e = d.getElementsByTagName(t)[0]; L.async = 1; L.src = '//feed.aqicn.org/feed/' + (c[n].city) + '/' + (c[n].lang || '') + '/feed.v1.js?n=' + n + k; e.parentNode.insertBefore(L, e); }; })(window, document, 'script', '_aqiFeed'); </script>
Depois, basta adicionar este outro código para incluir o widget:
<span id="city-aqi-container"></span> <script type="text/javascript" charset="utf-8"> _aqiFeed({ container: "city-aqi-container", city: "beijing" }); </script>
A função `_aqiFeed` toma como argumento o bloco de configuração do widget. O parâmetro `container: "city-aqi-container"` refere-se ao id da tag na qual você deseja inserir o widget (ex. `<span id='city-aqi-container'></span>`), e o parâmetro city é o nome da cidade para a qual você deseja mostrar a leitura atual da Qualidade do Ar (por exemplo, `cidade: "londres"`).
B. Especificando o idioma
Você também pode especificar o idioma a ser usado definindo a opção lang . Por exemplo, para incluir o widget em chinês (conforme mostrado à direita), use o seguinte código:
_aqiFeed({ container:"city-aqi-container", city:"beijing", lang:"cn" });
Os idiomas atualmente suportados são:
"en": English"cn": Chinese"jp": Japanese"es": Spanish"kr": Korean"ru": Russian"hk": Traditional Chinese"fr": French"pl": Polish"de": German"pt": Portuguese"vn": Vietnamese"it": Italian"id": Indonesian"nl": Dutch"fa": Persian"th": Thai"hu": Hungarian"el": Greek"ro": Romanian"bg": Bulgarian"ur": Urdu"hi": Hindi"ar": Arabic"sr": Serbian"bn": Bangla"hu": Hungarian"bs": Bosnian"hr": Croatian"tr": Turkish"uk": Ukrainian"cs": Czech"be": Belarusian"km": Khmer"lo": Lao Se não for especificado ou definido como null , o inglês será usado.
C. Especificando o formato de exibição
on Sunday 21:00
É possível personalizar o texto a ser exibido no widget especificando a opção display . Por exemplo, para exibir tanto o nome textual "AQI" quanto o tempo de atualização (conforme mostrado no widget à esquerda), você pode usar o seguinte código:
_aqiFeed({ display:"%cityname AQI is %aqi<br><small>on %date</small>", container:"city-aqi-container-display", city:"beijing" });
O parâmetro display é uma string baseada em HTML e pode conter qualquer uma das seguintes palavras-chave:
- `%cityname` para o nome da cidade (por exemplo,
Beijing), - `%aqi` para o valor AQI decorado (por exemplo,
58), - `%aqiv` para o valor AQI não decorado (texto bruto) (por exemplo,
58), - `%style` para a declaração css dos detalhes AQI decorados (por exemplo
background-color: #ffde33;color:#000000;), - `%date` para o horário em que o AQI foi atualizado (por exemplo,
Wed 20:00), - `%impact` para o impacto na saúde associado (por exemplo,
Good,Moderate...) - `%attribution` para atribuição de dados AQI (por exemplo
Beijing Environmental Protection Monitoring Center) - `%details` para obter os detalhes completos do AQI (o conteúdo do pop-up exibido ao mover o mouse sobre o valor do AQI).
Aqui estão alguns exemplos:
| Display Configuration | Result | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| %cityname Air Quality is <b>%impact</b>. | Beijing Air Quality is Unhealthy. | |||||||||
| %aqi <small>(%impact)</small> | 159 (Unhealthy) | |||||||||
| <span style='%style;font-size:12px;padding:5px 10px;'>%cityname AQI: %impact</span> | Beijing AQI: Unhealthy | |||||||||
| %cityname Air Quality is <span style='%style;padding:0 5px'>%impact</span> (%aqiv on %date) | Beijing Air Quality is Unhealthy
( 159 on Sunday 21:00) | |||||||||
| %cityname Air Quality is provided by %attribution | Beijing Air Quality is provided by Beijing Environmental Protection Monitoring Center (北京市环境保护监测中心) | |||||||||
| <div style='%style;max-width:180px;text-align:center;'><small>%cityname AQI:</small> <div style='font-size:88px;height:60px;padding-top:30px;'>%aqiv</div> %impact</div> | Beijing AQI:
159 | |||||||||
| %details | 159
Unhealthy
Updated on Sunday 21:00
|
D. Retorno de chamada programático
Se preferir a integração DIY, você também pode especificar um retorno de chamada de função javascript quando os dados forem carregados. Você só precisa adicionar a opção callback no bloco de parâmetros, como por exemplo:
_aqiFeed({ city:"beijing", callback:function(aqi){ /* Do whatever you want with the AQI object */ console.log(aqi); } });
Por exemplo, supondo que você também esteja usando jquery, o seguinte código:
<div id='my-container'></div> <script type="text/javascript" charset="utf-8"> _aqiFeed({ city: "beijing", lang: "pl", callback: function (aqi) { $("#my-container").html(aqi.details); } }); </script>
produzirá o seguinte conteúdo:
 | 159 | |
 | 77 | |
 | 51 |
Os objetos aqi contêm todas as palavras-chave mencionadas na seção C (formato de exibição).
E. Incluindo vários widgets
É possível incluir vários widgets em uma única página. Tudo que você precisa é passar para a função `_aqiFeed` um array com todos os widgets que você precisa incluir. Por exemplo, para inserir Londres, Paris e Nova York, pode-se usar este código:
The result is:var cities = ["london", "newyork", "seoul", "guangzhou", "tokyo", "shanghai", "paris","hongkong"]; var aqiWidgetConfig = []; cities.forEach(function(city) { aqiWidgetConfig.push({city:city, callback: displayCity}); }); _aqiFeed(aqiWidgetConfig); function displayCity(aqi) { $("#mutiple-city-aqi").append(aqi.text("<center>%cityname<br>%aqi<br><small>%date</small></center>")); }
F. Uso de feed
Este feed de widget é fornecido gratuitamente e com o único propósito de integrar o feed em outros sites (ou seja, os aplicativos estão excluídos) e sob a condição de uso razoável e aceitável. Reservamo-nos o direito de alterar a estrutura do feed (formato dos dados) a qualquer momento e sem aviso prévio, por isso é melhor entrar em contato conosco se você planeja fazer uma integração personalizada.
Ao fazer a integração, existem algumas regras deontológicas que devem ser aplicadas ao utilizar o feed de dados:
- Primeiro, certifique-se sempre de que a atribuição ao EPA de origem esteja presente. Todos os dados de qualidade do ar que você pode encontrar no projeto Índice Mundial de Qualidade do Ar são graças ao trabalho árduo de todas as EPAs em todo o mundo, portanto, certifique-se de fornecer também a atribuição de seu trabalho. Se você usar a API programática, a atribuição estará disponível no campo
attribution. - Se você é de uma instituição e utiliza os dados, por favor, mostre respeito e devolva os créditos pelo nosso trabalho. Se você está tentando copiar o feed de dados, por favor, tenha em mente que este projeto depende de projetos de patrocínio e cooperação, então considere nos apoiar em vez de nos descartar, especialmente se você for uma instituição ou universidade de grande porte.
- Na verdade, não aja como o WRI ( World Resource Institute ): descartando o feed de dados geral do projeto do Índice Mundial de Qualidade do Ar e sendo tão barato que eles nem sequer dariam qualquer atribuição ao nosso trabalho, e isso apesar de seus 80 milhões de financiamentos anuais em dólares. Não acredite em nós? Verifique este instantâneo .
G. Melhorias futuras
Esta é a primeira versão desta nova API de feed de widget. Já existem algumas melhorias em andamento, como largura e altura gráfica ajustáveis, escala AQI selecionável, etc. Se você quiser sugerir alguma outra melhoria específica, sinta-se à vontade para nos enviar uma mensagem.
