object-view-box

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

object-view-box 這個 CSS 屬性在可替換元素中定義一個矩形作為可視區域（視區），從而可以縮放或平移可替換元素的內容。它的工作方式類似於 SVG 的 viewBox 屬性。

試一試

object-view-box: inset(0 0);

object-view-box: inset(20%);

object-view-box: xywh(95px 20px 60px 60px);

object-view-box: rect(110px 120px 200px 45px);

object-view-box: none;

<section id="default-example">
  <img
    class="transition-all"
    id="example-element"
    src="/shared-assets/images/examples/plumeria-146x200.jpg"
    alt="A close-up of red flowers and buds on a branch." />
</section>

#example-element {
  height: 100%;
  width: 100%;
  border: 2px dotted #888888;
}

@supports not (object-view-box: none) {
  body::before {
    content: "Your browser does not support the 'object-view-box' property.";
    color: black;
    background-color: #ffcd33;
    display: block;
    width: 100%;
    text-align: center;
  }
}

語法

css

/* keywords */
object-view-box: none;

/* <basic-shape-rect> functions */
object-view-box: inset(20%);
object-view-box: inset(20% 30%);
object-view-box: inset(10px 0 25px 33px);
object-view-box: xywh(95px 20px 60px 60px);
object-view-box: rect(10px 30px 30px 10px);

/* Global values */
object-view-box: inherit;
object-view-box: initial;
object-view-box: revert;
object-view-box: revert-layer;
object-view-box: unset;

值

none: 元素沒有視區。這是預設值。
<basic-shape-rect>: 一個 inset()、xywh() 或 rect() 函式，為具有自然尺寸（可替換元素）的元素指定一個視區。否則，解析為 none。

描述

object-view-box 屬性可用於裁剪或調整可替換元素的大小，包括影像和影片。它的工作原理是在為該元素保留的可用空間中顯示可替換元素內容的一部分。顯示的可替換元素的部分由該屬性的值定義。可用的保留空間由元素的預設外部尺寸決定。顯示的內容子區域可以放大、縮小或以其原始尺寸呈現，同時保持內容的固有寬高比。

該屬性值為 <basic-shape-rect>，是 <basic-shape> 函式中僅限於定義矩形形狀的一種。例如，該值可以是 xywh() 函式

css

img {
  object-view-box: xywh(410px 0 400px 150px);
}

在這種情況下，將要顯示的影像部分的左上角距離左邊緣 410px，距離頂部 0，這由 x 和 y 座標引數定義。將要顯示的原始影像部分的大小為 400px 寬、150px 高；即函式的 w 和 h 分量。這個 400x150 的影像部分將顯示在頁面佈局時為影像本身保留的空間中。顯示的內容部分是其原始固有尺寸、放大還是縮小，分別取決於視區是 400px x 150px、小於還是大於影像元素的尺寸。

The leopard image cropped using object-view-box property, with a 400px by 150px viewbox displaying an unscaled section of the image

在這種情況下，由於 object-view-box 屬性定義的矩形視區和 <img> 元素的矩形區域大小相同，即 400 x 150 畫素，因此可替換元素沒有被縮放。

減小 w 和 h 的值可以產生放大效果；因為較小的影像部分被拉伸，所以有放大效果。

增加 w 和 h 引數的值可以產生縮小效果；因為較大的影像部分被收縮，所以有縮小效果。

對 x 和 y 座標進行動畫處理，透過移動元素的視區而元素本身保持在原位，從而產生平移效果。

正式定義

初始值	`none`
應用於	可替換元素
繼承性	否
計算值	指定的關鍵字或計算出的函式
動畫型別	如有可能則平滑過渡，否則離散

正式語法

object-view-box = 
  none                |
  <basic-shape-rect>  

<basic-shape-rect> = 
  <inset()>  |
  <rect()>   |
  <xywh()>   

<inset()> = 
  inset( <length-percentage>{1,4} [ round <'border-radius'> ]? )  

<rect()> = 
  rect( <top> , <right> , <bottom> , <left> )  

<xywh()> = 
  xywh( <length-percentage>{2} <length-percentage [0,∞]>{2} [ round <'border-radius'> ]? )  

<length-percentage> = 
  <length>      |
  <percentage>  

<border-radius> = 
  <length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?

示例

基本用法

本示例演示了 object-view-box 屬性的基本用法和效果，並使用了三個不同的 <basic-shape-rect> 函式作為示例。

HTML

我們有三個幾乎相同的 <img> 元素，包裹在 <figure> 元素中；唯一的區別是它們的類名。

html

<figure>
  <img
    class="intrinsic"
    src="https://mdn.github.io/shared-assets/images/examples/painted-hand.jpg"
    alt="Original scale section of a painted hand" />
  <figcaption>intrinsic</figcaption>
</figure>
<figure>
  <img
    class="zoom-in"
    src="https://mdn.github.io/shared-assets/images/examples/painted-hand.jpg"
    alt="Zoomed in section of a painted hand" />
  <figcaption>zoomed in</figcaption>
</figure>
<figure>
  <img
    class="zoom-out"
    src="https://mdn.github.io/shared-assets/images/examples/painted-hand.jpg"
    alt="Zoomed out section of a painted hand" />
  <figcaption>zoomed out</figcaption>
</figure>

CSS

我們為所有影像設定了相同的寬度和高度，然後為每個類（即每個影像）設定了不同的 object-view-box 值。彩繪手影像的固有尺寸為 298px x 332px。我們設定了 height 和 width，將外部尺寸設定為 200px x 200px。

css

img {
  width: 200px;
  height: 200px;
  border: 1px solid red;
}

我們使用三個不同的形狀函式設定了三個不同的 object-view-box 屬性值。intrinsic 元素的 xywh() 函式值顯示了一個 200px 的正方形影像內容區域，從左側 70px 和頂部 90px 處開始。zoom-in 元素的 rect() 函式顯示了原始元素的一個 160px 的正方形區域，從上邊緣的 110px 到 270px，以及從左邊緣的 90px 到 250px。zoom-out 可替換元素的 inset() 函式顯示了原始元素的一個 298px 的正方形區域；顯示了影像的整個寬度，同時從頂部和底部各裁剪了 17px。

css

.intrinsic {
  object-view-box: xywh(70px 90px 200px 200px);
}

.zoom-in {
  object-view-box: rect(110px 250px 270px 90px);
}

.zoom-out {
  object-view-box: inset(17px 0 17px 0);
}

@supports not (object-view-box: none) {
  body::before {
    content: "Your browser does not support the 'object-view-box' property.";
    color: black;
    background-color: #ffcd33;
    display: block;
    width: 100%;
    text-align: center;
  }
}

figure {
  display: inline-block;
  margin: 0;
}

figcaption {
  text-align: center;
}

結果

intrinsic 版本顯示的是未縮放的影像部分。zoom-in 版本顯示的是影像的一個較小部分（160px 正方形），被放大以適應 200px 正方形的視區。由於該部分被拉伸，看起來是放大的。zoom-out 版本顯示的是影像的一個較大部分（298px 正方形），被縮小以適應 200px 正方形的視區。由於該部分被收縮，看起來是縮小的。

使用 object-view-box 屬性即時放大

此示例演示瞭如何使用 object-view-box 屬性在靜態大小的 HTML 元素內放大和縮小可替換元素的一部分。在本例中，一張非常大的影像中豹子的眼睛作為縮放效果的焦點。

HTML

我們包含一個 <img> 元素和一個 range <input> 元素，以及一個關聯的 <label>。原始豹子影像的自然尺寸，即固有尺寸，為 1244px 寬、416px 高，寬高比為 3:1。

html

<img
  src="https://mdn.github.io/shared-assets/images/examples/leopard.jpg"
  alt="leopard" />
<p>
  <label for="box-size">Zoom-in: </label>
  <input type="range" id="box-size" min="115" max="380" value="150" />
</p>
<output></output>

CSS

我們定義了一個 --box-size 自定義屬性，它在 xywh() 函式中用作高度和寬度，從而建立了一個寬高比為 1:1 的正方形視區。視區的偏移點，即我們縮放效果的焦點，x 座標設定為 500px，y 座標設定為 30px，這對應於豹子右眼的左上角。

input {
  width: 350px;
}

output {
  text-align: center;
  background-color: #dedede;
  font-family: monospace;
  padding: 5px;
  display: block;
}

@supports not (object-view-box: none) {
  body::before {
    content: "Your browser does not support the 'object-view-box' property.";
    color: black;
    background-color: #ffcd33;
    display: block;
    width: 100%;
    text-align: center;
  }
}

css

img {
  width: 350px;
  height: 350px;
  border: 2px solid red;

  --box-size: 150px;
  object-view-box: xywh(500px 30px var(--box-size) var(--box-size));
}

JavaScript

我們為滑塊新增一個事件監聽器，當用戶與之互動時，更新 --boxSize 自定義屬性的值。為了在滑塊向右移動時增加放大效果，滑塊的值透過從 500px 中減去它來反轉，因為減小視區尺寸會增加放大效果。

const img = document.querySelector("img");
const zoom = document.getElementById("box-size");
const output = document.querySelector("output");

function update() {
  const size = 500 - zoom.value;
  img.style.setProperty("--box-size", `${size}px`);
  output.innerText = `object-view-box: xywh(500px 30px ${size}px ${size}px);`;
}

zoom.addEventListener("input", update);
update();

結果

向右移動滑塊以增加放大效果，向左移動以減少放大效果。滑塊隻影響視區的尺寸，而 x 和 y 值（視區的原點）保持不變。<img> 元素的尺寸也不變。

使用 object-view-box 屬性進行平移

此示例演示了透過對 object-view-box 屬性值進行動畫處理來平移影像。

HTML

HTML 中包含一張圖片。

html

<img
  src="https://mdn.github.io/shared-assets/images/examples/leopard.jpg"
  alt="leopard" />

CSS

我們定義一個影像尺寸，並保持視區尺寸（即 xywh() 函式的 w 和 h 分量）不變，同時對頂部和左側位置進行動畫處理，在五秒內改變 x 和 y 引數的位置。

css

img {
  width: 350px;
  height: 350px;

  object-view-box: xywh(0 30px 400px 400px);

  animation: panning 5s linear infinite alternate;
}

@keyframes panning {
  from {
    object-view-box: xywh(0 -50px 400px 400px);
  }
  to {
    object-view-box: xywh(800px 68px 400px 400px);
  }
}

@supports not (object-view-box: none) {
  body::before {
    content: "Your browser does not support the 'object-view-box' property.";
    color: black;
    background-color: #ffcd33;
    display: block;
    width: 100%;
    text-align: center;
  }
}

結果

規範

規範
CSS 影像模組 Level 5 # propdef-object-view-box

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ⁨2025 年 10 月 17 日⁩，由 MDN 貢獻者們修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題