使用方法

MediaTheme 是反色表面上的提供者，用在图片叠字、遮罩、toast 和 tooltip 上。它设置 data-astryx-media，让文字、图标和按钮改用深底或浅底上的颜色。它自己不铺背景，背景写在父元素上。

mode 必填：dark、light、auto 或 off。auto 测量父元素实际画出来的颜色（半透明的几层会叠在一起算），再看主题自己的 --color-on-dark 和 --color-on-light 哪个在上面更清楚，就选哪一边；周围文字对比已经达到 3:1 时选 off。背景图片没法从 CSS 量出来。表面颜色变了会重新测量。fallback 是还没量到、或量不到时用的一边，默认 dark。off 仍渲染这个元素，只是去掉媒体属性，子节点不会被拆掉重建。

useMediaTheme() 返回解析后的模式。两者都从 @astryx-vue/core/Theme 引入。

<script setup lang="ts">
import { MediaTheme } from '@astryx-vue/core/Theme'
</script>

<template>
  <div style="background: var(--astryx-color-background-inverted, #171717)">
    <MediaTheme mode="auto">
      <p>Readable on this surface</p>
    </MediaTheme>
  </div>
</template>

主题可以用 defineTheme() 的 onDark 和 onLight 给这些表面加 token。

最佳实践

指引	实践
推荐	用在深色图片、遮罩，或其他需要反色的表面上。
推荐	表面颜色来自主题 token 时，优先用 mode="auto"。
推荐	背景写在父元素上。MediaTheme 只翻转 token。
避免	用它做整页深色模式。整页用 Theme 的 mode="dark" 或 mode="system"。

示例

MediaTheme — Image Overlay

Product launch livestream MediaTheme keeps overlay text and controls readable without hard-coded color overrides.

常见的图片卡片：文字和操作放在深色渐变上，并用 MediaTheme mode="dark" 包住。

MediaTheme — Light Scrim

Bright media surface Use mode="light" when content sits on a light card or scrim.

图片上的浅色遮罩。用 MediaTheme mode="light"，文字和 ghost 按钮走浅底上的深色。