Skyroc Native UI

Tag

标签，用于状态标记与分类

标签（Tag）用于给内容打上状态、分类或属性标记。文字色通过 TextClassContext 下发，所以任意 children（图标、自定义 Text）都能继承标签的前景色。

import { Tag } from '@skyroc/native-ui';

视觉变体

variant 控制视觉强度，从高到低：

变体表现适用场景
solid语义底色 + 前景色文字强调状态（默认）
tonal15% 低饱和底色 + 同语义文字常规标记
outline语义描边，背景透明与内容并列的分类
ghost仅文字，无底色无描边最弱的辅助信息
TagVariant.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const VARIANTS = ['solid', 'tonal', 'outline', 'ghost'] as const;

const TagVariant = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {VARIANTS.map(v => (
        <Tag
          key={v}
          variant={v}
        >
          {v}
        </Tag>
      ))}
    </View>
  );
};

export { TagVariant };

语义颜色

color 提供 7 种语义色，各变体下的表现不同，逐一列出：

solid

底色为 bg-{color}，文字取对应的 {color}-foreground；muted 只有底色，文字统一是 text-muted-foreground。

TagColorSolid.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const COLORS = ['primary', 'destructive', 'secondary', 'success', 'warning', 'info', 'muted'] as const;

const TagColorSolid = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {COLORS.map(c => (
        <Tag
          key={c}
          color={c}
        >
          {c}
        </Tag>
      ))}
    </View>
  );
};

export { TagColorSolid };

tonal

底色为 bg-{color}/15（muted 是 bg-muted/50），文字是语义色本身。

TagColorTonal.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const COLORS = ['primary', 'destructive', 'secondary', 'success', 'warning', 'info', 'muted'] as const;

const TagColorTonal = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {COLORS.map(c => (
        <Tag
          key={c}
          color={c}
          variant="tonal"
        >
          {c}
        </Tag>
      ))}
    </View>
  );
};

export { TagColorTonal };

outline

描边为 border-{color}，背景透明；secondary 与 muted 都取中性的 border-border。

TagColorOutline.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const COLORS = ['primary', 'destructive', 'secondary', 'success', 'warning', 'info', 'muted'] as const;

const TagColorOutline = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {COLORS.map(c => (
        <Tag
          key={c}
          color={c}
          variant="outline"
        >
          {c}
        </Tag>
      ))}
    </View>
  );
};

export { TagColorOutline };

ghost

只保留语义文字色，没有底色和描边。

TagColorGhost.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const COLORS = ['primary', 'destructive', 'secondary', 'success', 'warning', 'info', 'muted'] as const;

const TagColorGhost = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {COLORS.map(c => (
        <Tag
          key={c}
          color={c}
          variant="ghost"
        >
          {c}
        </Tag>
      ))}
    </View>
  );
};

export { TagColorGhost };

secondary 在 tonal / outline / ghost 下的文字取 text-foreground —— 次级色本身太浅，直接当文字色读不清。

尺寸

尺寸高度字号水平内边距关闭图标
sm2010610
md2412812
lg28141014
TagSize.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const TagSize = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      <Tag size="sm">sm</Tag>
      <Tag size="md">md</Tag>
      <Tag size="lg">lg</Tag>
    </View>
  );
};

export { TagSize };

形状

形状圆角
roundedrounded-md（默认）
pill全圆角，药丸形
mark只有右侧全圆角，标记形
TagShape.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const TagShape = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      <Tag shape="rounded">rounded</Tag>
      <Tag shape="pill">pill</Tag>
      <Tag shape="mark">mark</Tag>
    </View>
  );
};

export { TagShape };

可关闭

closeable 在标签末尾渲染关闭按钮，点击触发 onClose。组件不会自己消失 —— 是否从列表里移除由你的状态决定。

TagCloseable.tsx
Loading…
import { Tag, Text } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';

const TagCloseable = () => {
  const [visible, setVisible] = useState(true);
  const [closeCount, setCloseCount] = useState(0);

  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      {visible ? (
        <Tag
          closeable
          closeAccessibilityLabel="移除筛选条件"
          onClose={() => setVisible(false)}
        >
          可移除
        </Tag>
      ) : (
        <Text className="text-sm text-muted-foreground">标签已移除</Text>
      )}
      <Tag
        closeable
        color="success"
        onClose={() => setCloseCount(current => current + 1)}
      >
        仅响应事件
      </Tag>
      <Text className="text-sm text-muted-foreground">onClose 次数：{closeCount}</Text>
    </View>
  );
};

export { TagCloseable };

关闭按钮的热区按尺寸补到约 30pt（sm 补 10、md 补 9、lg 补 8）：标签本身只有 20–28pt 高，补到 44pt 会大幅越过标签边界、与相邻标签互抢点击。按钮带 role="button" 与 accessibilityLabel（默认「关闭」，可用 closeAccessibilityLabel 改写）。

自定义内容

leading 放置前置图标，children 传 string / number 时自动包一层 Text，传节点时原样渲染并继承标签的文字色。

TagCombined.tsx
Loading…
import { Tag, Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TagCombined = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      <Tag
        leading={<Text>★</Text>}
        variant="tonal"
      >
        前置内容
      </Tag>
      <Tag color="info">
        <View className="flex-row items-center gap-1">
          <Text>自定义节点</Text>
          <Text className="opacity-70">2</Text>
        </View>
      </Tag>
      <Tag color="warning">2026</Tag>
    </View>
  );
};

export { TagCombined };

矢量图标不认 className，取色请用 withUniwind 把 accent-* 映射到 color。

样式覆盖

className 追加到根节点上，classNames 按 slot 细粒度覆盖：

slot作用位置
root根容器（底色、描边、圆角、尺寸）
text文字类名，通过 TextClassContext 下发给子 Text
close关闭按钮容器
closeIcon关闭图标的 colorClassName，只接受 accent-* 颜色类
TagStyles.tsx
Loading…
import { Tag } from '@skyroc/native-ui';
import { View } from 'react-native';

const TagStyles = () => {
  return (
    <View className="flex-row flex-wrap items-center gap-3 bg-background p-4">
      <Tag
        closeable
        className="h-8 border border-primary/30 bg-primary/10 px-3"
        classNames={{ close: 'rounded-full bg-primary/10 p-0.5', closeIcon: 'accent-primary', text: 'text-primary' }}
        variant="ghost"
      >
        自定义标签
      </Tag>
    </View>
  );
};

export { TagStyles };

API

Tag

除下表外，Tag 透传 View 的属性（style、testID 等）。

属性说明类型默认值
variant视觉变体'solid' | 'tonal' | 'outline' | 'ghost''solid'
color语义颜色'primary' | 'destructive' | 'secondary' | 'success' | 'warning' | 'info' | 'muted''primary'
size尺寸，同时控制高度、字号与内边距'sm' | 'md' | 'lg''md'
shape形状'rounded' | 'pill' | 'mark''rounded'
children标签内容，string / number 会被自动包裹为 TextReactNode-
leading前置内容，显示在文字之前ReactNode-
closeable是否显示关闭按钮booleanfalse
onClose关闭按钮点击回调；组件不会自行移除() => void-
closeAccessibilityLabel关闭按钮的无障碍标签string'关闭'
className根容器类名，合并在 classNames.root 之后string-
classNames各 slot 的类名覆盖，见「样式覆盖」一节SlotClassNames<TagSlots>-
ref底层 View 的 ref，用于 measure / 滚动定位Ref<View>-

类型

import type { TagColor, TagProps, TagShape, TagSize, TagSlots, TagVariant } from '@skyroc/native-ui';

TagVariant

标签视觉变体，强度从强到弱。

'solid' | 'tonal' | 'outline' | 'ghost'

TagColor

标签语义颜色。

'primary' | 'destructive' | 'secondary' | 'success' | 'warning' | 'info' | 'muted'

TagSize

标签尺寸，同时控制高度、字号、内边距与关闭图标大小。

'sm' | 'md' | 'lg'

TagShape

标签形状。

'rounded' | 'pill' | 'mark'

TagSlots

可通过 classNames 覆盖的 slot 名称。

'close' | 'closeIcon' | 'root' | 'text'

SlotClassNames

classNames 的取值形态：把 slot 名映射到类名，每个 slot 都可选。本页用到的 slot 见 TagSlots。

Partial<Record<Slots, string>>

包内还导出了 tagVariants 与三个常量：DEFAULT_TAG_SIZE、CLOSE_ICON_SIZE_MAP（关闭图标像素大小）、CLOSE_HIT_SLOP_MAP（关闭按钮热区补偿）。

Badge

标记数量或状态的角标组件

CountDown

按格式展示剩余时间的倒计时组件