# useTheme

## 使用方法

用代码拿主题 token 的值。给不吃 CSS 的地方用：SVG、canvas、Vega、D3、地图、图表库，它们要的是 JavaScript 里的具体值，而不是一个 CSS 变量名。

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

```ts
const { mode, token, tokens } = useTheme()

const accent = token('--color-accent')
const categorical = tokens.value['--color-data-categorical-blue']
```

## 建议

| 指引 | 做法 |
| --- | --- |
| 推荐 | 在 Vue 组件里往 SVG 属性、canvas 绘制、图表配置这类非 CSS 的对象里填颜色时，用 `tokens` 或 `token(name)`。 |
| 推荐 | 普通组件样式优先用 CSS 变量；只有 JavaScript 真需要具体值时才用这个 hook。 |
| 推荐 | 图表系列色用 `--color-data-categorical-blue` 这类数据可视化 token，不要随手挑一个界面颜色。 |
| 避免 | 在数据可视化里把浅色和深色写死：应该从当前主题解析出来。 |
| 避免 | 以为这个 hook 能反映所有 CSS 层叠覆盖。它只按当前 `Theme` 的模式解析；局部的媒体表面覆盖、以及外来的任意 CSS，不一定能体现出来。 |

## 示例

常见配置、变体和状态。

### useTheme — 读取 token 值

用 useTheme 读出解析后的 token 值，给 SVG 图表这类不吃 CSS 的地方用。

```vue
<script setup lang="ts">
import { Code } from '@astryx-vue/core/Code'
import { HStack, VStack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { useTheme } from '@astryx-vue/core/Theme'

const theme = useTheme()

const samples = ['--color-accent', '--color-background-surface', '--color-text-primary']
</script>

<template>
  <VStack :gap="3">
    <Text color="secondary">
      {{ theme.name.value }} · {{ theme.mode.value }}
    </Text>
    <Text weight="semibold">
      Resolved token values
    </Text>
    <HStack
      v-for="name in samples"
      :key="name"
      :gap="4"
      align="center"
      justify="between"
    >
      <Code color="secondary">
        {{ name }}
      </Code>
      <Code>{{ theme.token(name) }}</Code>
    </HStack>
  </VStack>
</template>
```

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `name` | `ComputedRef<string>` | 最近一层主题的名字。没有 `Theme` 时是 `neutral`。 |
| `mode` | `ComputedRef<'light' \| 'dark'>` | 实际生效的颜色模式。`system` 已经解析成 `light` 或 `dark`。 |
| `token` | `(name: string) => string` | 按当前模式把一个设计 token 解析成实际的 CSS 值。不在 `Theme` 里时，读的是文档根元素上的自定义属性。 |
| `tokens` | `ComputedRef<Record<string, string>>` | 最近一层主题声明的 token，按当前模式解析后的结果。`[浅色, 深色]` 会收成一个值。主题或模式不变时结果是稳定的。 |

token 名两种写法都可以：<code>--color-accent</code> 或 <code>--astryx-color-accent</code>。