# 语法主题

## 使用方法

`SyntaxTheme` 是代码颜色的提供者。它给里面的每个 `CodeBlock` 写上 `--astryx-code-syntax-*` 和 `--astryx-code-block-background`。`useSyntaxTheme()` 读取最近的语法主题，也包括 `defineTheme({ syntax })` 带上的那份。

单个代码块可以直接传 `syntaxTheme`。一整块区域共用一套预设时，用 `SyntaxTheme` 包起来。

预设从 `@astryx-vue/core/Code` 导出：`oneDarkPro`、`dracula`、`monokai`、`nord`、`tokyoNight`、`catppuccinMocha`、`githubDark`、`githubLight`、`solarizedLight`、`oneLight`、`catppuccinLatte`、`tokyoNightLight`。`defineSyntaxTheme()` 用来做自定义主题。14 个颜色 token 都要给。差异行另外有五个可选槽，名字仍是 `--astryx-code-syntax-*`：`added`、`removed`、`diff-header`、`added-marker`、`removed-marker`。不写时，标记跟着标点色，差异头不另铺底色。`[浅色, 深色]` 会存成 `light-dark()`。

```vue
<script setup lang="ts">
import { CodeBlock, dracula, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `const status = response.ok ? 'success' : 'error'`
</script>

<template>
  <SyntaxTheme :theme="dracula">
    <CodeBlock :code="code" language="ts" />
  </SyntaxTheme>
</template>
```

## 最佳实践

| 指引 | 实践 |
| --- | --- |
| 推荐 | 整个应用共用一套代码配色时，写在 <code>defineTheme()</code> 的 <code>syntax</code> 上。 |
| 推荐 | 只有某一段要换预设时，用 <code>SyntaxTheme</code>。 |
| 推荐 | 只有一个 <code>CodeBlock</code> 时，直接传 <code>syntaxTheme</code>，不必再包一层。 |
| 避免 | 用一次性 CSS 给代码块上色。预设会把 token 颜色和背景放在一起。 |

## 示例

### SyntaxTheme — Dark Preset

用 SyntaxTheme 包住代码块，套上 Dracula 这类深色预设。

```vue
<script setup lang="ts">
import { CodeBlock, dracula, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `function greet(name: string) {
  return \`Hello, \${name}!\`;
}`
</script>

<template>
  <SyntaxTheme :theme="dracula" style="width: min(100%, 420px)">
    <CodeBlock :code="code" language="tsx" title="Dracula preset" width="100%" />
  </SyntaxTheme>
</template>
```

### SyntaxTheme — Light Preset

浅色文档上的代码示例，用 GitHub Light 这类浅色预设。

```vue
<script setup lang="ts">
import { CodeBlock, githubLight, SyntaxTheme } from '@astryx-vue/core/Code'

const code = `const status = response.ok ? 'success' : 'error';
console.log({status});`
</script>

<template>
  <SyntaxTheme :theme="githubLight" style="width: min(100%, 420px)">
    <CodeBlock :code="code" language="tsx" title="GitHub Light preset" width="100%" />
  </SyntaxTheme>
</template>
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `theme` | `SyntaxThemeDefinition` | — | 内置预设，或 `defineSyntaxTheme()` 返回的主题。 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| `default` | 继承这些颜色的代码组件。 |

## Token

`keyword`、`string`、`comment`、`number`、`function`、`type`、`variable`、`operator`、`constant`、`tag`、`attribute`、`property`、`punctuation`、`background`。

## useSyntaxTheme

附近没有 `SyntaxTheme`，主题上也没有 `syntax` 时，返回 `null`。

| 字段 | 说明 |
| --- | --- |
| <code>name</code> | 语法主题名。 |
| <code>mode</code> | 用来挑选 <code>light-dark()</code> 哪一边的模式。 |
| <code>token(name)</code> | 该模式下的一个语法 token。 |
| <code>tokens</code> | 该模式下的全部语法 token。 |

## 原生属性

根节点是 `div`。`class` 和 `style` 会写到它上面。