ray()

**ray()** CSS 函数 定义了 offset-path 线段，动画元素可以沿着它移动。该线段被称为“射线”。射线从 offset-position 开始，并沿指定角度的方向延伸。可以通过指定大小并使用 contain 关键字来限制射线的长度。

语法

css
/* all parameters specified */
offset-path: ray(50deg closest-corner contain at 100px 20px);

/* two parameters specified, order does not matter */
offset-path: ray(contain 200deg);

/* only one parameter specified */
offset-path: ray(45deg);

参数

参数可以以任何顺序指定。

<angle>

<angle>

指定线段从偏移起始位置延伸的方向。角度 0deg 位于指向顶部的 y 轴上，正角度沿顺时针方向增加。

<size>

指定线段的长度，即 offset-distance 0% 和 100% 之间的距离，相对于包含框。这是一个可选参数（如果未指定 <size>，则使用 closest-side）。它接受以下关键字值之一

closest-side：射线起点与元素 包含块 最近一侧之间的距离。如果射线起点位于包含块的边缘，则线段的长度为零。如果射线起点位于包含块外部，则包含块的边缘被视为延伸到无穷大。这是默认值。

closest-corner：射线起点与元素包含块最近的角之间的距离。如果射线起点位于包含块的角上，则线段的长度为零。

farthest-side：射线起点与元素包含块最远一侧之间的距离。如果射线起点位于包含块外部，则包含块的边缘被视为延伸到无穷大。

farthest-corner：射线起点与元素包含块最远的角之间的距离。

contain

sides：射线起点与线段与包含块边界相交的点之间的距离。如果起点位于包含块边界上或外部，则线段的长度为零。

contain

缩短线段的长度，以便即使在 offset-distance: 100% 时，元素也保持在包含块内。具体而言，该段的长度将缩短元素边框框的宽度或高度的一半，取两者中较大者，且永远不小于零。这是一个可选参数。

描述

ray() 函数通过指定元素在二维空间中的角度和距离参考点（极坐标）的位置，将元素沿着路径定位。此功能使 ray() 函数可用于创建 2D 空间过渡。相比之下，这种方法不同于通过元素相对于固定原点的水平和垂直距离（直角坐标）来指定点的方法，该方法由 translate() 函数使用，也不同于通过动画将元素沿着定义的路径移动。

由于 ray() 在 2D 空间中工作，因此必须考虑元素的初始位置和方向。当 ray() 函数作为元素的 offset-path 值应用时，您可以通过以下方式控制这些方面：

  • 元素最初是通过将元素的 offset-anchor 点移动到元素的偏移起始位置来定位的。默认情况下，光线的起始位置由 offset-position 值确定。如果 offset-position 明确指定为 normal（或省略并允许默认为 normal），则元素将定位在其包含块的 center（或 50% 50%）处。指定 offset-position: auto 将起始位置设置为元素位置的 top left 角（或 0 0）。
  • 元素最初旋转，使其 内联轴（其文本流方向）与 ray() 指定的角度对齐。例如，对于 ray() 角度为 0deg 的情况，该角度位于指向上的 y 轴上，元素的内联轴将旋转为垂直方向以匹配光线角度。元素在整个路径中保持此旋转。要自定义此行为，请使用 offset-rotate 属性，该属性允许您为元素指定不同的旋转角度或方向，从而能够更精确地控制其沿着路径移动时的外观。例如，设置 offset-rotate: 0deg 将移除 ray() 应用的任何旋转，将元素的内联轴与文本流方向对齐。

正式语法

<ray()> = 
  ray( <angle>          &&
  <ray-size>?           &&
  contain?              &&
  [ at <position> ]? )  

<ray-size> = 
  closest-side     |
  closest-corner   |
  farthest-side    |
  farthest-corner  |
  sides            

<position> = 
  [ left | center | right | top | bottom | <length-percentage> ]  |
  [ left | center | right ] && [ top | center | bottom ]  |
  [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]  

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

示例

定义光线角度和起始位置

此示例展示了如何使用元素的起始位置以及元素的方向如何受指定的光线角度的影响。

CSS

css
.box {
  background-color: palegreen;
  border-top: 4px solid black;
  opacity: 20%;
}

.box:first-of-type {
  position: absolute;
}

.box1 {
  offset-path: ray(0deg);
}

.box2 {
  offset-path: ray(150deg);
}

.box3 {
  offset-rotate: 0deg;
  offset-position: 20% 40%;
  offset-path: ray(150deg);
}

.box4 {
  offset-position: 0 0;
  offset-path: ray(0deg);
}

.box5 {
  offset-path: ray(60deg closest-side at bottom right);
}

类似于 transform-origin，默认锚点位于元素的中心。可以使用 offset-anchor 属性修改此锚点。

在此示例中，将各种 offset-path: ray() 值应用于编号为 1 到 5 的框。每个框的“包含块”用虚线边框表示。左上角的淡出框显示了每个框在不应用任何 offset-position 或 offset-path 时的默认位置，以便进行并排比较。每个框的顶部用 solid 边框突出显示，以说明光线起始点和方向的变化。在定位到光线的起始点后，框会与指定的光线角度方向对齐。如果未指定 offset-position，则光线的默认偏移起始位置为框包含块的中心（或 50% 50%）。

结果

  • box1 的初始定位方式使其锚点（其中心）位于默认偏移起始位置（包含块的 50% 50%）。box1 还旋转以使其朝向光线的 0deg 角度。这将成为路径的起点。您可以通过将框与左侧的淡出 box0 进行比较来观察框的位置和旋转的变化。框旋转以匹配沿 y 轴指向上的 0deg 角度。框旋转从框内数字的方向可以明显看出。
  • 在 box2 中，对光线应用了更大的正角度 150deg，以显示光线角度是如何工作的。从左上角开始，框按顺时针方向旋转以达到指定的 150deg 角度。
  • box2 和 box3 具有相同的 offset-path 值。在 box3 中，还对元素应用了 offset-rotate 的 0deg。因此，元素将始终以该特定角度旋转，并且元素不会沿路径方向旋转。请注意，在 box3 中，光线路径为 150deg，但由于 offset-rotate 的原因，框的方向不会沿着路径发生变化。还要注意，box3 的 offset-path 属性没有指定起始 <position>，因此光线的起始位置来自元素的 offset-position，在本例中为 top 20% left 40%。
  • box4 的 offset-position 设置为包含块的左上角（0 0），因此元素的锚点和偏移起始位置重合。在该起始点对元素应用了 0deg 的光线角度。
  • 在 box5 中，offset-path 属性指定 at <position> 值，该值将框放置在元素包含块的 bottom 和 right 边缘，并将 60deg 应用于光线的角度。

沿着光线动画化元素

在此示例中，第一个形状作为参考显示其位置和方向。在其他形状上应用光线运动路径。

CSS

css
body {
  display: grid;
  grid-template-columns: 200px 100px;
  gap: 40px;
  margin-left: 40px;
}

.container {
   transform-style: preserve-3d;
   width: 150px;
   height: 100px;
   border: 2px dotted green;
}

.shape {
  width: 40px;
  height: 40px;
  background: #2bc4a2;
  margin: 5px;
  text-align: center;
  line-height: 40px;
  clip-path: polygon(0% 0%, 70% 0%, 100% 50%, 70% 100%, 0% 100%, 30% 50%);
  animation: move 5000ms infinite alternate ease-in-out;
}

.shape2 {
  offset-path: ray(120deg sides contain);
}

.shape3 {
  offset-rotate: 0deg;
  offset-path: ray(120deg sides contain);
}

.shape4 {
  offset-position: auto;
  offset-path: ray(120deg closest-corner);
}

.shape5 {
  offset-position: auto;
  offset-path: ray(120deg farthest-corner);
}

@keyframes move {
  0%, 20% {
    offset-distance: 0%;
  }
  80%, 100% {
    offset-distance: 100%;
  }

结果

在应用 offset-path 的前两个示例中，请注意形状在没有 offset-rotate 和有 offset-rotate 时的方向。这两个示例都使用默认的 offset-position 值 normal，因此，路径运动从 50% 50% 开始。最后两个 offset-path 示例显示了角 <size> 值的影响：closest-corner 和 farthest-corner。closest-corner 值创建了一个非常短的偏移路径，因为形状已经位于角上（offset-position: auto）。farthest-corner 值创建了最长的偏移路径，从包含块的左上角到右下角。

规范

规范
运动路径模块级别 1
# ray-function

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅