JGuang
EN

加载指示

Spinner · Astryx

交互预览
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

加载指示 · Spinner

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

  • 加载指示 · 综合展示 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'浅色或深色背景的颜色色调。
labelReactNode旋转器下方的可见内容。字符串标签自动设置 aria-label。
aria-labelstring'Loading'屏幕阅读器的无障碍名称。默认为 label（如果是字符串）或来自 i18n 词条的已翻译 "Loading"。
xstyleStyleXStylesStyleX 样式，用于布局自定义（边距、定位、尺寸）。必须是 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

{
  "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 度），各尺寸相同"
    }
  ]
}