useSurface

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

useSurface(options?)

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

useSurface 签名

const ref = useSurface<HTMLElement>(options);

在现有组件间共享光照

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 中的光照。

useSurface options
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。