跳转到正文

Surface材质表面

通用表面容器;正文用 solid/frosted,浮动层可显式使用 glass。

Alpha

为内容与浮动功能层选择不同材质,避免重复 backdrop 采样。

引入

TSX
import { Surface } from "@cwa-design/react";
import "@cwa-design/react/styles.css"; // 应用入口引入一次

当前通过源码 workspace 使用。查看有效安装步骤 →

交互示例

可切换示例主题、开启实色降级并重置状态。应用根部需要 CwaProvider。

Surface 基础用法

可运行示例 · 与复制源码同源

正在准备交互示例…

surface-basic
查看与复制源码
TSX
// 应用入口引入 @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 基础用法

可运行示例 · 与复制源码同源

正在准备交互示例…

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 (
    <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"
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 配置会启用回退。

阅读材质指南 →

关联 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 →

无障碍与使用约束

  • semantic-content
  • visible-focus-for-interactive-parts
  • keyboard-behavior-from-native-or-base-ui

这些是组件契约与使用要求。具体业务页面仍需验证标签、阅读顺序与实际背景下的对比度。

查看无障碍使用指南 →