Surface材质表面
通用表面容器;正文用 solid/frosted,浮动层可显式使用 glass。
为内容与浮动功能层选择不同材质,避免重复 backdrop 采样。
引入
import { Surface } from "@cwa-design/react";
import "@cwa-design/react/styles.css"; // 应用入口引入一次当前通过源码 workspace 使用。查看有效安装步骤 →
交互示例
可切换示例主题、开启实色降级并重置状态。应用根部需要 CwaProvider。
Surface 基础用法
可运行示例 · 与复制源码同源
正在准备交互示例…
查看与复制源码
// 应用入口引入 @cwa-design/react/styles.css,并将此示例置于 CwaProvider 内。
import { Surface, Text } from "@cwa-design/react";
export default function Example() {
return (
<Surface material="glass" style={{ padding: "1.5rem" }}>
<Text>浮动层的 regular glass 表面</Text>
</Surface>
);
}
在应用根部引入 styles.css 并配置 CwaProvider。源码 SHA-256:0e358f5029d1
Surface 基础用法
可运行示例 · 与复制源码同源
正在准备交互示例…
查看与复制源码
// 应用入口引入 @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 (
<div
style={{
position: "relative",
width: "100%",
maxWidth: "26rem",
minHeight: "15rem",
borderRadius: "1.25rem",
overflow: "hidden",
// 自绘媒体背景(无第三方素材):亮=晨光草坡,暗=夜色山谷。
background: dark
? "radial-gradient(circle at 78% 18%, #e8ecf5 0 7%, rgba(232,236,245,0) 7.6%), linear-gradient(152deg, #0a1220 0%, #152238 52%, #0a1322 100%)"
: "radial-gradient(circle at 76% 20%, #fffbe8 0 9%, rgba(255,251,232,0) 9.6%), linear-gradient(152deg, #9fd4f2 0%, #fdf1d8 46%, #a8d489 46.2%, #5f9e5c 100%)",
}}
>
<Surface
material="glass-clear"
style={{
position: "absolute",
left: "1rem",
right: "1rem",
bottom: "1rem",
display: "flex",
alignItems: "center",
gap: "0.75rem",
padding: "0.625rem 0.875rem",
borderRadius: "1rem",
}}
>
<IconButton
variant="secondary"
size="sm"
label={playing ? "暂停演示" : "播放演示"}
aria-pressed={playing}
onClick={() => setPlaying(!playing)}
>
<span aria-hidden="true">{playing ? "Ⅱ" : "▶"}</span>
</IconButton>
<div style={{ flex: 1, minWidth: 0 }}>
<Text as="p" style={{ margin: 0, fontWeight: 590 }}>
{dark ? "夜色山谷" : "高山晨光"}
</Text>
<Text as="p" tone="muted" variant="caption" style={{ margin: 0 }}>
Clear:媒体上的轻工具栏
</Text>
</div>
<IconButton variant="secondary" size="sm" label="收藏到媒体库">
<span aria-hidden="true">♡</span>
</IconButton>
</Surface>
</div>
);
}
在应用根部引入 styles.css 并配置 CwaProvider。源码 SHA-256:56e225a98ce1
API
下表读取本版本组件契约。原生与 Base UI 继承属性的完整定义保留在 TypeScript 声明中。
类型:SurfaceProps · 继承 React.HTMLAttributes<HTMLDivElement>;className/style、DOM 事件、aria-*、data-* 均由原生类型继承 · 候选源类型 ↗
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
material | 见类型定义 | "solid" | "frosted" | "glass" | "glass-clear" | "solid" |
children | ReactNode;内容由调用方提供 | 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 或深色主题。
适用的状态与行为见示例及本页 API;系统减少透明与显式 solid 配置会启用回退。
阅读材质指南 →关联 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无障碍与使用约束
semantic-contentvisible-focus-for-interactive-partskeyboard-behavior-from-native-or-base-ui
这些是组件契约与使用要求。具体业务页面仍需验证标签、阅读顺序与实际背景下的对比度。
查看无障碍使用指南 →