# 引文

## 使用方法

`Citation` 在一句话里标出来源。`label` 是带标题的小胶囊。`number` 是紧凑的上标。`number` 从 1 开始，会读进无障碍名称，数字变体也会把它画出来。

`source.url` 有值时，引文是在新标签页打开的链接，并带 `role="doc-noteref"`。没有 URL 时是 `<span>`，不会假装自己是链接。无障碍名称会本地化，例如「引用 2：发布说明」。`source.title` 为空时，可见文字回退到编号。

`source.icon` 优先于 `source.src`。看起来像 URL 或路径的值画成图片，其他字符串交给 `Icon` 当 CSS 类名。图标只在 label 变体里出现。

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

<template>
  <p>
    参见
    <Citation :number="1" :source="{ title: '发布说明', url: 'https://example.com/notes' }" />
    <Citation :number="1" variant="number" :source="{ title: '发布说明', url: 'https://example.com/notes' }" />
  </p>
</template>
```

## 建议

| 建议 | 做法 |
| --- | --- |
| 推荐 | 同一次回答里，同一个来源保持同一个 `number`，胶囊和上标才指向同一条。 |
| 推荐 | `title` 写读者认得出的名字。编号只是没有标题时的退路。 |
| 推荐 | 段落很密时用数字变体；希望不看脚注也能读出来源时用 label。 |
| 避免 | 把一整句放进 `title`。胶囊会截断，无障碍名称也会变成那一整句。 |
| 避免 | 拿引文当普通链接。它是注记，不是导航。 |

### 结构

- **容器**: 根容器。来源地址可用时渲染成链接；缺失或被拒绝时渲染成不起作用的 span。
- **图标**: 标签文字前面的可选来源图标。可以是网站图标或标志的图片地址（source.src），也可以是插槽内容，比如 Astryx 的 Icon。只在标签变体里可用。
- **标签文字**: 来源标题。超过最大宽度时用省略号截断。标签变体里显示。
- **编号**: 显示成上标徽章的引用序号。编号变体里显示。

## 示例

### Citation — 行内文字

引文嵌在段落里，和周围的字走在同一行。

```vue
<script setup lang="ts">
import { Citation } from '@astryx-vue/core/Citation'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <Stack direction="vertical" :gap="4" style="max-width: 560px">
    <Text type="body">
      React uses a virtual DOM to minimize expensive DOM operations<Citation
        :number="1"
        variant="number"
        :source="{ title: 'React Documentation', url: 'https://react.dev' }"
      />. This approach was inspired by earlier functional UI frameworks<Citation
        :number="2"
        variant="number"
        :source="{ title: 'Elm Architecture', url: 'https://guide.elm-lang.org/architecture/' }"
      />.
    </Text>
    <Text type="body">
      TypeScript adds static types to JavaScript for safer refactoring<Citation
        :number="3"
        variant="label"
        :source="{ title: 'TypeScript Documentation', url: 'https://www.typescriptlang.org', icon: 'https://www.typescriptlang.org/favicon-32x32.png' }"
      />.
    </Text>
  </Stack>
</template>
```

### Citation — 来源列表

回答或文章末尾的来源列表，每条都带图标。

```vue
<script setup lang="ts">
import { Citation } from '@astryx-vue/core/Citation'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'

const sources = [
  { title: 'React Documentation', url: 'https://react.dev', icon: 'https://react.dev/favicon-32x32.png' },
  { title: 'TypeScript Handbook', url: 'https://www.typescriptlang.org/docs/handbook/', icon: 'https://www.typescriptlang.org/favicon-32x32.png' },
  { title: 'MDN Web Docs', url: 'https://developer.mozilla.org', icon: 'https://developer.mozilla.org/favicon-48x48.cbbd161b.png' },
  { title: 'W3C WAI-ARIA Specification', url: 'https://www.w3.org/TR/wai-aria/' },
]
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Text type="supporting" color="secondary">
      Sources
    </Text>
    <Stack direction="horizontal" :gap="2" style="flex-wrap: wrap">
      <Citation
        v-for="(source, index) in sources"
        :key="source.title"
        :source="source"
        :number="index + 1"
        variant="label"
      />
    </Stack>
  </Stack>
</template>
```

## 属性

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `source` | `CitationSource` | - | `title` 是可见标题，空着就回退到编号。`url` 会渲染成链接。`src` 是站点图标。`icon` 是图片地址或 CSS 图标类，优先于 `src`。 |
| `number` | `number` | - | 从 1 开始的序号。会读进无障碍名称，数字变体也会显示它。 |
| `variant` | `'label' \| 'number'` | `'label'` | `label` 是带标题的胶囊。`number` 是紧凑的上标。 |

模板引用暴露 <code>element</code>，也就是那个链接或 span。

## 主题

`packages/themes/neutral/citation.css` 把组件变量映射到语义 token。换主题时覆盖这些变量即可。

- `--astryx-citation-foreground` / `--astryx-citation-foreground-hover`：默认和悬停时的文字颜色。
- `--astryx-citation-border` / `--astryx-citation-hover`：胶囊边框和悬停底色。
- `--astryx-citation-number-background`：上标底色。
- `--astryx-citation-icon-background`：label 图标后面的圆。
- `--astryx-citation-focus`：键盘焦点描边。
- `--astryx-duration-fast-max` / `--astryx-ease-standard`：悬停过渡。

## 原生属性

属性落到根节点上。有 `source.url` 时根节点是 `<a>`，否则是 `<span>`。`target`、`rel`、`role`、`aria-label` 和 `title` 由组件自己设置。