[组件 ](/cwa-design/components/)/基础 # Surface材质表面通用表面容器；正文用 solid/frosted，浮动层可显式使用 glass。 Alpha 为内容与浮动功能层选择不同材质，避免重复 backdrop 采样。 [交互示例 ](#examples)[API ](#api)[Storybook ↗ ](/cwa-design/storybook/)[Registry ↗ ](/cwa-design/downloads/registry/0.1.0-alpha.4/manifest.json) ## 引入 TSX复制 ``` import { Surface } from "@cwa-design/react"; import "@cwa-design/react/styles.css"; // 应用入口引入一次 ``` 当前通过源码 workspace 使用。[查看有效安装步骤 → ](/cwa-design/docs/getting-started/) ## 交互示例可切换示例主题、开启实色降级并重置状态。应用根部需要 CwaProvider。 ### Surface 基础用法可运行示例 · 与复制源码同源重置正在准备交互示例… surface-basic示例主题跟随网站浅色示例深色示例实色降级查看与复制源码TSX复制 ``` // 应用入口引入 @cwa-design/react/styles.css，并将此示例置于 CwaProvider 内。 import { Surface, Text } from "@cwa-design/react"; export default function Example() { return ( 浮动层的 regular glass 表面 ); } ``` 在应用根部引入 styles.css 并配置 CwaProvider。源码 SHA-256：0e358f5029d1 ### Surface 基础用法可运行示例 · 与复制源码同源重置正在准备交互示例… surface-clear-toolbar示例主题跟随网站浅色示例深色示例实色降级查看与复制源码TSX复制 ``` // 应用入口引入 @cwa-design/react/styles.css，并将此示例置于 CwaProvider 内。 // Clear 材质专用样张：照片/媒体上的轻量工具栏。 // 浅色 Clear 配亮调媒体、深色 Clear 配暗调媒体——两种组合都保持文字对比度。 import { IconButton, Surface, Text, useCwaContext } from "@cwa-design/react"; import { useState } from "react"; export default function Example() { const context = useCwaContext(); const dark = context.resolvedTheme === "dark" || context.theme === "dark"; const [playing, setPlaying] = useState(false); return (

setPlaying(!playing)} >

{dark ? "夜色山谷" : "高山晨光"} Clear：媒体上的轻工具栏

); } ``` 在应用根部引入 styles.css 并配置 CwaProvider。源码 SHA-256：56e225a98ce1 ## API 下表读取本版本组件契约。原生与 Base UI 继承属性的完整定义保留在 TypeScript 声明中。类型：SurfaceProps · 继承 React.HTMLAttributes；className/style、DOM 事件、aria-*、data-* 均由原生类型继承 · [候选源类型 ↗ ](/cwa-design/downloads/source/packages/react/src/surface/surface.tsx) 属性说明类型默认值 material见类型定义"solid" | "frosted" | "glass" | "glass-clear""solid" childrenReactNode；内容由调用方提供ReactNode；内容由调用方提供— ## 材质与状态实色内容材质规则来自源 metadata。覆盖玻璃区域的浮层按实际重叠关系选择较厚或实色材质。默认 solid；frosted 轻分离；glass=regular；glass-clear 仅媒体控件显式启用。Provider solid 与系统回退优先。背景可读性（默认 Token 实测：2 主题 × 11 背景 × 4 材质，Chromium 1440×1000，未取整 4.5:1，逐包围框采样）：regular 的正文与控件标签除“深色×纯白”（正文样本实测最低 3.910:1，<4.5）外全部 ≥4.5:1；regular 副文字仅保证中等亮度背景（山水/文字列表/图表/棋盘）与同向极端背景（浅色×纯白、深色×纯黑）。默认已测压力背景（存在 <4.5:1 样本，请改 frosted/solid 或给控件局部实色底面）：浅色×{暗插画, 明暗分区, 纯黑}、深色×{亮插画, 纯白}。glass-clear 用于完整表单属不推荐用途（同向极端背景仍实测可达标）；作为媒体轻工具栏按媒体逐个验证：深色主题的真实亮/暗照片实测通过，浅色主题的真实照片与明暗分区实测失败。显式 tint/accent 覆盖不在默认矩阵范围内，采用后需在实际背景复查。 ### 真实媒体上的 Clear 工具栏 Clear 的受支持用法是媒体上的轻工具栏；逐媒体检查可读性，不把自绘渐变样张的结论推广到所有媒体。真实亮照片真实暗照片自绘明暗分区压力（默认已测失败）：浅色主题的 Clear 在真实照片的混合亮暗区域低于 4.5:1（亮照片实测最低 1.134、暗照片 1.642、分区 2.519）。请改用 Regular/Thick 或深色主题。 ▶高山晨光Clear：媒体上的轻工具栏 ♡ 适用的状态与行为见示例及本页 API；系统减少透明与显式 solid 配置会启用回退。 [阅读材质指南 → ](/cwa-design/design/materials/) ## 关联 Token 以下变量从组件源样式的实际引用生成。共享光学规则还使用全局玻璃 Token。 --cwa-design-radius-panel--cwa-design-color-text--cwa-design-font-family--cwa-design-focus-width--cwa-design-color-focus--cwa-design-focus-offset--cwa-design-color-surface--cwa-design-color-border-subtle [在主题实验室调整公开 Token → ](/cwa-design/themes/) ## 无障碍与使用约束 - semantic-content - visible-focus-for-interactive-parts - keyboard-behavior-from-native-or-base-ui 这些是组件契约与使用要求。具体业务页面仍需验证标签、阅读顺序与实际背景下的对比度。 [查看无障碍使用指南 → ](/cwa-design/design/accessibility/) ## 相关组件 [CwaProvider全局配置 ](/cwa-design/components/provider/)[Button按钮 ](/cwa-design/components/button/)[IconButton图标按钮 ](/cwa-design/components/icon-button/)