# 加载指示 · Spinner

- 页面: https://jiguang132.com/zh/resources/astryx/docs/spinner
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

加载指示用于反馈与状态场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **加载指示 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **加载指示 · 交互示例 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **加载指示 · 尺寸变化 / 尺寸 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **加载指示 · 包含标签 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Spinner

An animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | 旋转器尺寸——环直径（10px、14px、18px、28px）。 |
| shade | 'default' \| 'onMedia' \| 'subtle' \| 'inherit' | 'default' | 浅色或深色背景的颜色色调。 |
| label | ReactNode |  | 旋转器下方的可见内容。字符串标签自动设置 aria-label。 |
| aria-label | string | 'Loading' | 屏幕阅读器的无障碍名称。默认为 label（如果是字符串）或来自 i18n 词条的已翻译 "Loading"。 |
| xstyle | StyleXStyles |  | StyleX 样式，用于布局自定义（边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。 |

### 使用建议

- Provide a meaningful label to describe what is loading for screen reader users.
- Use the "onMedia" shade when placed on dark or accent-colored backgrounds.
- 避免：Use for content areas with known dimensions; use Skeleton to preserve layout instead.
- 避免：Stack multiple spinners in the same view; use one to represent the overall loading state.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-spinner",
      "visualProps": [
        "size",
        "shade"
      ]
    }
  ],
  "vars": [
    {
      "name": "--spinner-diameter",
      "description": "绘制环的直径。在尺寸变体目标上设置，以重新定义每个命名尺寸的解析值，例如 spinner: { 'size:xl': { '--spinner-diameter': '2.5rem' } }。渲染盒子的尺寸为该值加上两侧的描边宽度，并自动跟随。支持任意长度单位——rem、em 与 calc() 会在绘制前解析。",
      "default": "10px (sm), 14px (md), 18px (lg), 28px (xl)"
    },
    {
      "name": "--spinner-stroke-width",
      "description": "绘制环的两个圆——移动圆弧与其后的轨道——的描边宽度。与直径一起按尺寸设置。同一个描边宽度同时驱动两者，因此 0 会被采纳为零宽描边——什么都不绘制，而不会回退到默认值；若想要没有轨道的圆弧，请改将 --spinner-track-color 设为 transparent。",
      "default": "2px (sm), 3px (md), 3px (lg), 4px (xl)"
    },
    {
      "name": "--spinner-color",
      "description": "运动圆弧的颜色。默认取所在 shade 的令牌，因此可在 shade 变体目标上设置以重新定义单个 shade——spinner: { 'shade:subtle': { '--spinner-color': 'var(--color-text-tertiary)' } }——或在 base 目标上设置以覆盖全部四种。接受任意颜色写法，包括 var()、color-mix() 与 currentColor。",
      "default": "var(--color-accent)（default）、var(--color-text-secondary)（subtle）、var(--color-on-dark)（onMedia）、currentColor（inherit）"
    },
    {
      "name": "--spinner-track-color",
      "description": "圆弧所在轨道的颜色。设为 `transparent` 可得到无轨道的圆弧。onMedia 与 inherit 两种 shade 会以降低的透明度（30%）绘制轨道，以便在任意背景上可辨；该淡化同样作用于主题化的颜色。",
      "default": "var(--color-track)（default、subtle）、var(--color-on-dark)（onMedia）、currentColor（inherit）"
    },
    {
      "name": "--spinner-arc-fraction",
      "description": "运动圆弧覆盖圆环的比例，为纯数字（非百分比或角度）。在尺寸变体目标上设置，方式与 --spinner-diameter 相同，例如 spinner: { 'size:xl': { '--spinner-arc-fraction': '0.75' } } 可得到 270 度的圆弧。仅在样式表加载后生效；无 CSS 的渲染（SSR、无 JS）始终绘制默认的 135 度圆弧。",
      "default": "0.375（135 度），各尺寸相同"
    }
  ]
}
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt