Element: getClientRects() 方法

Baseline 已廣泛支援

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

Element 介面的 getClientRects() 方法返回一個 DOMRect 物件集合，這些物件指示了客戶端中每個 CSS 邊框盒的邊界矩形。

大多數元素的邊框盒都只有一個，但多行的行內級元素（例如，預設情況下多行的 <span> 元素）的每行都有一個邊框盒。

返回值為一個 DOMRect 物件集合，對應於元素關聯的每個 CSS 邊框盒。每個 DOMRect 物件以畫素為單位描述邊框盒，其左上角相對於視口的左上角。對於帶標題的表格，即使標題在表格邊框盒之外，也會包含該標題。當在 <svg> 元素（外層 <svg> 除外）上呼叫時，生成的矩形所相對於的“視口”是其外層 <svg> 建立的視口（並且需要明確的是，如果外層 <svg> 有 viewBox 變換，那麼矩形也會被該變換變換）。

在計算矩形時會考慮視口區域（或任何其他可滾動元素）的滾動量。

返回的矩形不包含可能溢位的任何子元素的邊界。

對於 HTML 的 <area> 元素、不自行渲染的 SVG 元素、display:none 的元素以及通常任何不直接渲染的元素，將返回一個空列表。

即使對於具有空邊框盒的 CSS 盒模型，也會返回矩形。left、top、right 和 bottom 座標仍然有意義。

可能存在畫素偏移的零頭數。

示例

這些示例以各種顏色繪製了客戶端矩形。請注意，繪製客戶端矩形的 JavaScript 函式透過類名 withClientRectsOverlay 與標記連線。

HTML

示例 1：此 HTML 建立了三個帶有內部 <span> 的段落，每個段落都包含在一個 <div> 塊中。客戶端矩形將繪製在第二個塊的段落以及第三個塊的 <span> 元素的上面。

html

<h3>A paragraph with a span inside</h3>
<p>
  Both the span and the paragraph have a border set. The client rects are in
  red. Note that the p has only one border box, while the span has multiple
  border boxes.
</p>

<div>
  <strong>Original</strong>
  <p>
    <span>Paragraph that spans multiple lines</span>
  </p>
</div>

<div>
  <strong>p's rect</strong>
  <p class="withClientRectsOverlay">
    <span>Paragraph that spans multiple lines</span>
  </p>
</div>

<div>
  <strong>span's rect</strong>
  <p>
    <span class="withClientRectsOverlay"
      >Paragraph that spans multiple lines</span
    >
  </p>
</div>

示例 2：此 HTML 建立了三個有序列表。客戶端矩形將繪製在第二個塊的 <ol> 以及第三個塊的每個 <li> 元素的上面。

html

<h3>A list</h3>
<p>
  Note that the border box doesn't include the number, so neither do the client
  rects.
</p>

<div>
  <strong>Original</strong>
  <ol>
    <li>Item 1</li>
    <li>Item 2</li>
  </ol>
</div>

<div>
  <strong>ol's rect</strong>
  <ol class="withClientRectsOverlay">
    <li>Item 1</li>
    <li>Item 2</li>
  </ol>
</div>

<div>
  <strong>each li's rect</strong>
  <ol>
    <li class="withClientRectsOverlay">Item 1</li>
    <li class="withClientRectsOverlay">Item 2</li>
  </ol>
</div>

示例 3：此 HTML 建立了兩個帶標題的表格。客戶端矩形將繪製在第二個塊的 <table> 元素的上面。

html

<h3>A table with a caption</h3>
<p>
  Although the table's border box doesn't include the caption, the client rects
  do include the caption.
</p>

<div>
  <strong>Original</strong>
  <table>
    <caption>
      caption
    </caption>
    <thead>
      <tr>
        <th>thead</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>tbody</td>
      </tr>
    </tbody>
  </table>
</div>

<div>
  <strong>table's rect</strong>
  <table class="withClientRectsOverlay">
    <caption>
      caption
    </caption>
    <thead>
      <tr>
        <th>thead</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>tbody</td>
      </tr>
    </tbody>
  </table>
</div>

CSS

CSS 分別為第一個示例中每個 <div> 塊內的段落和 <span> 繪製邊框；為第二個示例中的 <ol> 和 <li> 繪製邊框；為第三個示例中的 <table>、<th> 和 <td> 元素繪製邊框。

css

strong {
  text-align: center;
}
div {
  display: inline-block;
  width: 150px;
}
div p,
ol,
table {
  border: 1px solid blue;
}
span,
li,
th,
td {
  border: 1px solid green;
}

JavaScript

JavaScript 程式碼為所有具有 withClientRectsOverlay CSS 類分配的 HTML 元素繪製客戶端矩形。

function addClientRectsOverlay(elt) {
  /* Absolutely position a div over each client rect so that its border width
     is the same as the rectangle's width.
     Note: the overlays will be out of place if the user resizes or zooms. */
  const rects = elt.getClientRects();
  for (const rect of rects) {
    const tableRectDiv = document.createElement("div");
    tableRectDiv.style.position = "absolute";
    tableRectDiv.style.border = "1px solid red";
    const scrollTop =
      document.documentElement.scrollTop || document.body.scrollTop;
    const scrollLeft =
      document.documentElement.scrollLeft || document.body.scrollLeft;
    tableRectDiv.style.margin = tableRectDiv.style.padding = "0";
    tableRectDiv.style.top = `${rect.top + scrollTop}px`;
    tableRectDiv.style.left = `${rect.left + scrollLeft}px`;
    // We want rect.width to be the border width, so content width is 2px less.
    tableRectDiv.style.width = `${rect.width - 2}px`;
    tableRectDiv.style.height = `${rect.height - 2}px`;
    document.body.appendChild(tableRectDiv);
  }
}

(() => {
  /* Call function addClientRectsOverlay(elt) for all elements with
     assigned class "withClientRectsOverlay" */
  const elems = document.getElementsByClassName("withClientRectsOverlay");
  for (const elem of elems) {
    addClientRectsOverlay(elem);
  }
})();