首页 / Leaflet / API 文档

Util

先看结论

Leaflet 内部使用的一组通用函数，写自定义图层和控件时会反复用到。

最后验证 2026-11-03 · Leaflet 1.9.4 · 更新 2026-10-28 · 引用本文

L.Util.method(...) → 视函数而定

参数与返回值

函数	返回	说明
`extend(dest, ...src)`	Object	把后续对象的属性浅拷贝进第一个对象，返回它
`create(proto, properties?)`	Object	以 `proto` 为原型创建对象，可附加自有属性
`bind(fn, obj, ...args)`	Function	绑定 `this` 并预置参数
`stamp(obj)`	Number	给对象分配唯一 id 并缓存到 `obj._leaflet_id`，重复调用返回同一个值
`setOptions(obj, options)`	Object	合并选项到 `obj.options`，不存在时沿原型链创建
`template(str, data)`	String	把 `{key}` 占位符替换为 `data.key`，缺失时抛错
`getParamString(obj, existingUrl?, uppercase?)`	String	拼查询串；`uppercase` 默认 false，为 true 时参数名转大写
`wrapNum(x, range, includeMax?)`	Number	把数值折回 `[range[0], range[1]]`，`includeMax` 默认 false
`formatNum(num, precision?)`	Number	按位数四舍五入，`precision` 默认 6；传 `false` 跳过处理
`falseFn()`	false	始终返回 false 的空函数，用于占位
`isArray(obj)`	Boolean	数组判断
`throttle(fn, time, context)`	Function	节流包装，`time` 毫秒内最多执行一次
`requestAnimFrame(fn, context?, immediate?)`	Number	下一帧执行，返回可用于取消的 id
`cancelAnimFrame(id)`	undefined	取消 `requestAnimFrame` 排队

成员

成员	说明
`L.Util.emptyImageUrl`	1×1 透明 GIF 的 data URL，用于占位避免空 src 发请求
`L.Util.lastId`	当前已分配的最大 id
`L.Util.requestAnimFrame`	优先使用 `requestAnimationFrame`，降级到 setTimeout
`L.Util.template`	瓦片 URL 的 `{z}/{x}/{y}` 替换就是它做的
`L.Util.stamp`	FeatureGroup 的 `getLayer(id)` 依赖这个 id

/* 继承并合并默认选项，自定义图层常用写法 */
var HeatLayer = L.Layer.extend({
  options: { radius: 20, blur: 15, max: 1 },

  initialize: function (points, options) {
    L.Util.setOptions(this, options);
    this._points = points || [];
  }
});

/* 拼请求串：不要手写 & 和 ? */
L.Util.getParamString({ layers: 'a:b', format: 'image/png' }, '/wms?');
/* → /wms?layers=a%3Ab&format=image%2Fpng */

L.Util.template('https://tile.openstreetmap.org/{z}/{x}/{y}.png', { z: 12, x: 3372, y: 1552 });

/* 经度归一到 -180～180 */
L.Util.wrapNum(190, [-180, 180]);      /* → -170 */

L.Util.formatNum(116.391263, 4);       /* → 116.3913，默认保留 6 位 */

var icon = L.divIcon({ className: '', html: '<i></i>', iconSize: [10, 10] });
console.log(L.Util.stamp(icon));       /* 唯一 id，重复调用不变 */

formatNum 默认保留 6 位小数。不做坐标压缩时把 precision 传 false，可以跳过四舍五入，避免坐标先被截断再参与距离或面积计算，结果出现米级偏差。

template 遇到缺失的键会直接抛错，而不是留下占位符。URL 模板里的 {s} 之类可选段要提前保证数据里存在。自定义图层若覆盖了 options，先调用 L.Util.setOptions(this, options) 再合并父类默认值，否则父类选项会整体丢失。

引用本文

经纬志（2026）。《Util》。https://www.jingweizhi.com/leaflet/api/util.html（访问日期 2026-11-03）。