# React · useSurface

返回将现有 DOM 元素连接到光照的 ref。

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/zh/docs/react/use-surface/

<a id="use-surface"></a>

## useSurface(options?)

返回回调 ref，将现有 HTML 元素连接到最近的 Edge.Provider。将 ref 传给显示边框的元素，保留原有的 `className` 和 `style` 即可。

```tsx
const ref = useSurface<HTMLElement>(options);
```

```tsx
function Area() {
  return <Edge.Provider><ExistingCard /><ExistingCard /></Edge.Provider>;
}

function ExistingCard() {
  const ref = useSurface<HTMLDivElement>();
  return <Card ref={ref}>Your existing component</Card>;
}
```

React 18 的函数组件需要通过 `forwardRef` 将 ref 转发给 HTML 元素。React 19 也支持将 ref 作为 prop 接收。

未显式传入光照时，需要 Edge.Provider。要自行管理光照，请将 `useLight` 返回的句柄传给 `useSurface(light, options)`。显式传入的光照优先于 Edge.Provider 中的光照。

| Prop / 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | 装饰使用的伪元素。选择 before 可保留现有 ::after。若两者均被占用，或宿主为原生输入元素，请使用容器。无效值抛出 RangeError。 |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | 边缘对光照的响应方式。三种样式均保留组件原有外观。 |
| `color` | `string` | `currentColor` | 高光颜色。默认跟随DOM 元素的文字颜色。接受任意 CSS 颜色字符串，包括 CSS 变量。 |
| `shadowColor` | `string` | `#0008` | 相对边缘的颜色。接受任意 CSS 颜色字符串；使用 transparent 可移除浅色表面上的此阴影。 |
| `borderWidth` | `number` | `1` | 装饰边缘的厚度，单位为像素；不改变DOM 元素的边框。负数限制为 0，非有限值使用默认值。 |
| `intensity` | `number` | `1` | 共享光照强度的乘数。有限值限制在 0–1，非有限值使用默认值。 |

一个 DOM 元素只能连接一个光照。不要将 ref 传给尺寸不同的父元素。

选项更新不会替换元素。通过 Hook 连接的高光在水合后生效。如需在服务端 HTML 中包含相关 class 和 CSS 变量，请使用 `Edge.Surface`。