# React · Edge.Surface

为 DOM 元素应用光照效果。

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

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

## Edge.Surface

渲染一个连接到最近 Edge.Provider 的 HTML 元素。`as` 指定的标签决定可用的 HTML 属性、事件和 ref。

```tsx
<Edge.Surface as="article" edgeStyle="raised">
  Your content
</Edge.Surface>
```

| 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，非有限值使用默认值。 |
| `as` | `HTML tag name` | `'div'` | 要渲染的 HTML 元素。原生属性和 ref 随所选标签变化；此处不接受自定义 React 组件。 |
| `children` | `ReactNode` | `Unset` | DOM 元素内渲染的内容。输入等无法自行显示装饰的元素请使用容器。 |
| `ref` | `Ref<HTMLElement for the chosen tag>` | `Unset` | 与内部注册 ref 一起转发给渲染的元素。保留 React 19 回调 ref 的清理行为。 |
| `className` | `string` | `Unset` | 原有类名，与装饰类合并。 |
| `style` | `CSSProperties` | `Unset` | 原有内联样式，在装饰绑定之后合并。除非有意覆盖，请保留 Edge 管理的 CSS 变量。 |

`Edge.Surface` 必须在 `Edge.Provider` 内使用，否则渲染时会抛出错误。对于 input 元素或现有伪元素冲突，请参阅[集成注意事项](https://edge.bolerish.com/zh/docs/integration/)。

高光与 DOM 元素边框的外侧对齐。要连接现有组件渲染的 DOM 元素，请使用 [useSurface](https://edge.bolerish.com/zh/docs/react/use-surface/#use-surface)。