想練習 Ajax 的跨網域請求,天氣 API 是最合適的題目:介面單純、回傳結構清楚、畫面成果又看得見。本文以聚合數據的全國天氣預報介面為例。

文件位置:https://www.juhe.cn/docs/api/id/39
https://v.juhe.cn/weather/index實際串接前請先至官網申請自己的金鑰,切勿把金鑰硬編碼在前端程式碼中——前端程式碼對所有人都是可見的。正確作法是透過自己的後端代理請求,由後端保管金鑰。
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
<meta charset="UTF-8">
<title>天氣預報</title>
<script src="jquery-2.1.1.min.js"></script>
<link rel="stylesheet" href="w.css">
</head>
<body>
<div id="mf_weather">
<button id="search">天氣查詢</button>
<input id="city" type="text" value="臺北">
<div class="ctn">
<div id="mufeng"></div>
<div id="future"></div>
</div>
</div>
<script src="w.js"></script>
</body>
</html>
流程很清楚:輸入城市名 → 點擊時送出請求 → 成功後渲染頁面。
$('#search').on('click', function () {
var city = $('#city').val() || '北京';
var citycode = urlencode(city);
// 金鑰請替換為自己的,且正式環境應改由後端代理
var url = 'https://v.juhe.cn/weather/index?format=2&cityname='
+ citycode + '&key=YOUR_API_KEY';
$.ajax({
url: url,
dataType: "jsonp",
type: "get",
data: { location: city },
success: function (data) {
var sk = data.result.sk; // 目前實況
var today = data.result.today; // 今日
var futur = data.result.future; // 未來預報
$('#mufeng').html(
"<p>目前:" + sk.temp + "℃," + sk.wind_direction
+ sk.wind_strength + ",濕度 " + sk.humidity
+ ",更新時間 " + sk.time + "</p>" +
"<p>" + today.city + " 今天 " + today.date_y + " "
+ today.week + "," + today.temperature + ","
+ today.weather + "," + today.wind + "</p>"
);
$('#future').html(
"<p>明日:" + futur[0].temperature + "℃,"
+ futur[0].weather + "," + futur[0].wind
+ "(" + futur[0].week + " " + futur[0].date + ")</p>"
);
},
error: function (xhr, status) {
$('#mufeng').text('查詢失敗,請稍後再試。');
}
});
});
function urlencode(str) {
str = (str + '').toString();
return encodeURIComponent(str)
.replace(/!/g, '%21')
.replace(/'/g, '%27')
.replace(/\(/g, '%28')
.replace(/\)/g, '%29')
.replace(/\*/g, '%2A')
.replace(/%20/g, '+');
}
一、dataType 用了 jsonp,代表這是一段被執行的程式碼。JSONP 的原理是動態插入 script 標籤,瀏覽器會執行伺服器回傳的任何內容。因此只可對完全可信的來源使用;今日更推薦的作法是請後端代理請求,前端只呼叫自己的同網域介面,並以 CORS 處理真正的跨網域需求。
二、渲染時請改用 text 而非 html。把 API 回傳的文字直接串進 .html(),若其中含角括號就會破壞結構,這是典型的 XSS 途徑。上面範例中的欄位多為固定格式,但仍建議養成用 .text() 設定文字、用元素屬性設定數值的習慣。
三、記得處理失敗情況。城市名拼錯、金鑰額度用盡、網路逾時都會發生。至少要提供 error 回呼與使用者可理解的提示,而不是讓畫面一片空白。
這個練習涵蓋了 Ajax 串接第三方 API 的所有基本環節:參數編碼、非同步請求、結構化資料取值、畫面渲染與錯誤處理。把它做熟之後,替換成任何 RESTful API 都只是改 URL 與欄位名稱而已。