萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

JavaScript URL 參數獲取、修改與構建完整工具指南

核心 API:URLSearchParams (現代標準,推薦)

現代瀏覽器 (IE 無支援,需 Polyfill) 原生提供 URLSearchParams,功能完整、語意清晰。

基本操作

// 從當前 URL 獲取
var params = new URLSearchParams(window.location.search);

// 獲取值 (自動處理多值)
params.get("id");           // 第一個值
params.getAll("tag");       // 所有值陣列 ["a", "b"]
params.has("keyword");      // true/false

// 設定/新增/刪除
params.set("page", "2");        // 設定 (覆蓋所有同名)
params.append("tag", "js");     // 新增 (保留舊值)
params.delete("keyword");       // 刪除所有同名
params.sort();                  // 按鍵名排序

// 輸出查詢字串
params.toString(); // "id=123&page=2&tag=js&tag=css"

// 迭代
for (var [key, value] of params) { ... }
params.forEach(function(value, key) { ... });

完整 URL 構建

var url = new URL("https://example.com/search");
url.searchParams.set("q", "關鍵字");
url.searchParams.set("page", "2");
url.hash = "results";

console.log(url.href); 
// "https://example.com/search?q=%E9%97%9C%E9%8D%B5%E5%AD%97&page=2#results"

傳統瀏覽器相容方案:手工解析函式

原文提供的 changeURLPar 函式邏輯正確但代碼冗長。現代化重寫版:

/**
 * URL 參數工具集 (無依賴、IE9+ 相容)
 */
var UrlParams = {
  // 解析查詢字串為物件 { key: [val1, val2] }
  parse: function(search) {
    search = search || window.location.search;
    if (search.startsWith("?")) search = search.slice(1);
    if (!search) return {};
    
    var result = {};
    search.split("&").forEach(function(pair) {
      var idx = pair.indexOf("=");
      var key = decodeURIComponent(idx > 0 ? pair.slice(0, idx) : pair);
      var val = decodeURIComponent(idx > 0 ? pair.slice(idx + 1) : "");
      if (!result[key]) result[key] = [];
      result[key].push(val);
    });
    return result;
  },
  
  // 獲取單一值 (第一個)
  get: function(name, search) {
    var params = this.parse(search);
    return params[name] ? params[name][0] : null;
  },
  
  // 獲取所有值
  getAll: function(name, search) {
    var params = this.parse(search);
    return params[name] || [];
  },
  
  // 設定參數 (返回新 URL)
  set: function(url, name, value) {
    var urlObj = new URL(url, window.location.href); // 支援相對路徑
    if (value === null || value === undefined) {
      urlObj.searchParams.delete(name);
    } else {
      urlObj.searchParams.set(name, value);
    }
    return urlObj.href;
  },
  
  // 批次設定
  setMultiple: function(url, paramsObj) {
    var urlObj = new URL(url, window.location.href);
    Object.keys(paramsObj).forEach(function(key) {
      var val = paramsObj[key];
      if (val === null || val === undefined) {
        urlObj.searchParams.delete(key);
      } else if (Array.isArray(val)) {
        urlObj.searchParams.delete(key);
        val.forEach(function(v) { urlObj.searchParams.append(key, v); });
      } else {
        urlObj.searchParams.set(key, val);
      }
    });
    return urlObj.href;
  },
  
  // 移除參數
  remove: function(url, name) {
    return this.set(url, name, null);
  },
  
  // 保留指定參數,其餘移除
  keepOnly: function(url, keys) {
    var urlObj = new URL(url, window.location.href);
    var toDelete = [];
    urlObj.searchParams.forEach(function(_, key) {
      if (keys.indexOf(key) === -1) toDelete.push(key);
    });
    toDelete.forEach(function(key) { urlObj.searchParams.delete(key); });
    return urlObj.href;
  }
};

// 使用範例
var currentUrl = window.location.href;

// 獲取參數
var userId = UrlParams.get("userId"); 
var tags = UrlParams.getAll("tag"); 

// 修改單一參數
var newUrl = UrlParams.set(currentUrl, "page", "2");

// 批次修改
var newUrl2 = UrlParams.setMultiple(currentUrl, {
  page: 3,
  sort: "desc",
  tag: ["js", "vue", "react"] // 陣列自動展開為多個 tag
});

// 移除參數
var cleanUrl = UrlParams.remove(currentUrl, "debug");

// 導向新 URL
// location.href = newUrl;

jQuery 專用擴充 (若專案已用 jQuery)

$.extend({
  urlParams: {
    // 獲取當前頁參數物件 { key: value } (單值模式)
    getAll: function() {
      var params = {};
      var search = window.location.search.substring(1);
      search.split("&").forEach(function(pair) {
        var parts = pair.split("=");
        var key = decodeURIComponent(parts[0]);
        var val = decodeURIComponent(parts[1] || "");
        params[key] = val; // 同名後蓋前
      });
      return params;
    },
    
    // 獲取單一值
    get: function(name) {
      var match = window.location.search.match(new RegExp("[?&]" + name + "=([^&]*)"));
      return match ? decodeURIComponent(match[1]) : null;
    },
    
    // 設定參數並跳轉
    setAndGo: function(name, value) {
      var url = new URL(window.location.href);
      if (value === null || value === undefined) {
        url.searchParams.delete(name);
      } else {
        url.searchParams.set(name, value);
      }
      window.location.href = url.href;
    }
  }
});

// 使用
var params = $.urlParams.getAll();
var page = $.urlParams.get("page");
$.urlParams.setAndGo("theme", "dark");

實務場景範例

1. 分頁導航保留其他參數

function goPage(pageNum) {
  var url = UrlParams.setMultiple(window.location.href, { page: pageNum });
  location.href = url;
}

// 頁碼按鈕
$(".pagination a").click(function(e) {
  e.preventDefault();
  var page = $(this).data("page");
  goPage(page);
});

2. 篩選條件 URL 同步 (可分享、可重整、SEO 友善)

var FilterSync = {
  // 從 URL 恢復篩選狀態
  restore: function($form) {
    var params = UrlParams.parse();
    $form.find(":input[name]").each(function() {
      var $input = $(this);
      var name = $input.attr("name");
      var values = params[name];
      if (!values) return;
      
      if ($input.is(":checkbox")) {
        $input.prop("checked", values.includes($input.val()));
      } else if ($input.is(":radio")) {
        $input.prop("checked", $input.val() === values[0]);
      } else if ($input.is("select[multiple]")) {
        $input.val(values);
      } else {
        $input.val(values[0]);
      }
    });
  },
  
  // 篩選變更時更新 URL (不重整)
  bind: function($form, debounceMs) {
    var timer;
    $form.on("change", ":input", function() {
      clearTimeout(timer);
      timer = setTimeout(function() {
        var data = $form.serializeArray(); // [{name, value}, ...]
        var params = {};
        data.forEach(function(item) {
          if (!params[item.name]) params[item.name] = [];
          params[item.name].push(item.value);
        });
        // 移除空值
        Object.keys(params).forEach(function(k) {
          params[k] = params[k].filter(function(v) { return v !== ""; });
          if (params[k].length === 0) delete params[k];
        });
        
        var newUrl = UrlParams.setMultiple(window.location.href, params);
        history.replaceState(null, "", newUrl); // 不新增歷史記錄
      }, debounceMs || 300);
    });
  }
};

// 使用
$(function() {
  FilterSync.restore($("#filterForm"));
  FilterSync.bind($("#filterForm"));
});

3. 表單提交前清理空參數

$("#searchForm").on("submit", function(e) {
  // 移除空值參數,避免 ?keyword=&page=1
  var $form = $(this);
  $form.find(":input[value='']").prop("disabled", true); // disabled 不會提交
  
  // 或手動構建乾淨 URL
  var cleanUrl = UrlParams.keepOnly($form.attr("action"), 
    $form.serializeArray().map(function(f) { return f.name; })
  );
  $form.attr("action", cleanUrl);
});

URL 編碼陷阱與處理

函式用途編碼範圍範例
encodeURIComponent**查詢參數值**所有保留字符 + 空格"a b" → "a%20b"
encodeURI**完整 URL**保留 :/?#[]@!$&'()*+,;="https://a/b" → 不變
decodeURIComponent解碼參數值對應 encodeURIComponent"a%20b" → "a b"
decodeURI解碼完整 URL對應 encodeURI-
// 正確:參數值用 encodeURIComponent
var url = "/search?q=" + encodeURIComponent("中文 搜尋") + "&page=1";
// "/search?q=%E4%B8%AD%E6%96%87%20%E6%90%9C%E5%B0%8B&page=1"

// 錯誤:用 encodeURI 導致 & = 未編碼,破壞參數結構
var bad = "/search?q=" + encodeURI("a&b"); 
// "/search?q=a&b" → 解析為 q="a", b="" 兩個參數!

總結

現代專案**直接使用 URL 和 URLSearchParams** (需 IE Polyfill),API 完整、符合標準、可鏈式操作。舊專案可封裝 UrlParams 工具物件統一處理解析、修改、構建。關鍵原則:

  1. 參數值**必須** encodeURIComponent
  2. 使用 history.replaceState 同步 URL 不污染歷史
  3. 表單序列化用 serializeArray() 而非 serialize() 以保留陣列結構
  4. 避免手工字串拼接 URL,極易出錯
copyright © 萬盛學電腦網 all rights reserved