# useImageMode

## 使用方法

采样图片的像素，判断它整体偏暗还是偏亮。采样通过 `OffscreenCanvas` 进行，不往页面上画任何东西。亮度用 APCA 的感知亮度（先把 sRGB 线性化，再做一次幂曲线），饱和色也能判得准。整个过程不在绘制路径上：没有可见画布，也不会引起布局抖动。可以只采一块区域，用来判断文字浮层所在位置的亮度。还在加载时返回 `null`，跨域或网络失败时退回 `fallback`。

实现上会先 fetch 图片，画进 10×10 的离屏画布再取平均，所以 `src` 一变，还没回来的那次结果就作废。`src` 和 `options` 都可以写成 ref 或 getter。

```ts
import { useImageMode } from '@astryx-vue/core'
```

## 建议

| 指引 | 实践 |
| --- | --- |
| 推荐 | 和 `MediaTheme` 一起用，让图片上的文字颜色跟着背景图自动切换。 |
| 推荐 | 用 `region` 只采文字浮层会出现的那一块，结果更准。 |
| 避免 | 用在变化很快的图上（例如视频帧）；每次 `src` 变化都会重新拉取和分析。 |

## 参数

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `src` | `MaybeRefOrGetter<string \| null \| undefined>` | — | 要分析的图片地址。普通字符串、ref、getter 都行。为 null 或 undefined 时直接给 `fallback`。必填。 |
| `options` | `MaybeRefOrGetter` | `{}` | 分析的可选配置。每次分析时重新读，写成 getter 就能一直取到最新值。 |
| `options.region` | `ImageSampleRegion` | 整张图 | 只采这一块。坐标都按 0 到 1 的比例给出：`{ x, y, width, height }`。 |
| `options.threshold` | `number` | `0.5` | 分深浅的亮度阈值。低于算暗，高于算亮。 |
| `options.fallback` | `'dark' \| 'light' \| null` | `null` | 还在加载，或者读图失败时返回的值。 |

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `mode` | `Ref<'dark' \| 'light' \| null>` | 图片的深浅。还在加载时是 `null`，`src` 为空时是 `fallback`。 |

分析的两段也一起导出了：`perceptualLightness(r, g, b)` 返回一个颜色的 APCA 感知亮度，`imageModeFromPixels(pixels, threshold)` 把一段 RGBA 像素平均成 `'dark'` 或 `'light'`。