精確獲取元素位置是實現拖拽、定位提示、滾動監聽等互動功能的基礎。本文系統整理 jQuery 核心座標 API、座標系差異、跨瀏覽器坑點與原生替代方案。
// 獲取
var offset = $('#element').offset();
// 返回: { top: 150, left: 300 } - 相對 document (0,0)
// 設定 (改變元素位置,需 position: absolute/fixed)
$('#element').offset({ top: 200, left: 400 });
position 影響,永遠相對 <html>var pos = $('#element').position();
// 返回: { top: 20, left: 30 } - 相對最近的定位父層 (offsetParent)
offsetParent(最近的 position !== static 祖先)// 獲取/設定視口或元素滾動位置
$(window).scrollTop(); // 頁面垂直滾動距離
$('#container').scrollLeft(); // 容器水平滾動距離
// 平滑滾動到元素
$('html, body').animate({
scrollTop: $('#target').offset().top
}, 500);
// 1. 文件座標 → 視口座標 (扣除滾動)
function toViewportCoords(docX, docY) {
return {
x: docX - $(window).scrollLeft(),
y: docY - $(window).scrollTop()
};
}
// 2. 視口座標 → 文件座標
function toDocumentCoords(vpX, vpY) {
return {
x: vpX + $(window).scrollLeft(),
y: vpY + $(window).scrollTop()
};
}
// 3. 滑鼠事件座標標準化
function getEventCoords(e) {
e = e || window.event;
return {
// 視口座標
clientX: e.clientX,
clientY: e.clientY,
// 文件座標
pageX: e.pageX || (e.clientX + $(document).scrollLeft()),
pageY: e.pageY || (e.clientY + $(document).scrollTop()),
// 螢幕座標
screenX: e.screenX,
screenY: e.screenY
};
}
// 4. 元素中心點座標 (文件座標)
function getElementCenter($el) {
var offset = $el.offset();
return {
x: offset.left + $el.outerWidth() / 2,
y: offset.top + $el.outerHeight() / 2
};
}
| 問題 | 影響版本 | 解決方案 |
|---|---|---|
| fixed 元素 offset 不含滾動 | 舊版 jQuery/IE | 手動加上 scrollTop/Left |
| body 有 margin 導致偏移 | 所有 | CSS reset: body { margin: 0 } |
| transform 父層導致 offsetParent 錯誤 | Chrome 60+/Firefox | 使用 getBoundingClientRect() |
| iframe 跨域獲取位置失敗 | 所有 | postMessage 通訊 |
| display:none 元素 offset 為 0/報錯 | 所有 | 先顯示測量再隱藏,或用 getBoundingClientRect |
var rect = element.getBoundingClientRect();
// 返回 DOMRect: { x, y, width, height, top, right, bottom, left }
// 相對視口 (viewport),含 transform 縮放影響
// 轉文件座標
var docX = rect.left + window.scrollX;
var docY = rect.top + window.scrollY;
// 針對跨行的 等內聯元素,返回每個行框的矩形
var rects = element.getClientRects(); // DOMRectList
// 監聽元素進入/離開視口
var observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
console.log(entry.isIntersecting, entry.intersectionRatio, entry.boundingClientRect);
});
}, { threshold: [0, 0.5, 1] });
observer.observe(document.querySelector('#target'));
function positionTooltip($trigger, $tooltip) {
var triggerOffset = $trigger.offset();
var triggerH = $trigger.outerHeight();
var triggerW = $trigger.outerWidth();
var tipH = $tooltip.outerHeight();
var tipW = $tooltip.outerWidth();
var vpW = $(window).width();
var vpH = $(window).height();
var scrollTop = $(window).scrollTop();
var scrollLeft = $(window).scrollLeft();
// 預設:上方置中
var top = triggerOffset.top - tipH - 8;
var left = triggerOffset.left + triggerW/2 - tipW/2;
// 邊界檢測與調整
if (top < scrollTop) { // 上方空間不足 → 下方
top = triggerOffset.top + triggerH + 8;
$tooltip.addClass('tooltip-bottom');
}
if (left < scrollLeft) left = scrollLeft + 4;
if (left + tipW > scrollLeft + vpW) left = scrollLeft + vpW - tipW - 4;
$tooltip.css({ top, left }).show();
}
interface JQueryCoordinates {
top: number;
left: number;
}
interface JQuery {
offset(): JQueryCoordinates;
offset(coords: JQueryCoordinates): this;
position(): JQueryCoordinates;
scrollTop(): number;
scrollTop(value: number): this;
scrollLeft(): number;
scrollLeft(value: number): this;
}
// 原生擴充
interface Element {
getBoundingClientRect(): DOMRect;
}
interface Window {
scrollX: number;
scrollY: number;
}