Text

文本（Text）是对 React Native Text 的封装，提供 color / size / weight 三组变体，并通过 TextClassContext 从父组件（如 Button、Cell）继承文字样式。库内所有需要文字的组件都用它，因此在这些组件里放 @skyroc/native-ui 的 Text 才能自动拿到正确的文字色。

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

基础用法

不传任何变体时是前景色（text-foreground）、基础字号、normal 字重。

TextBasic.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextBasic = () => {
  return (
    <View className="bg-background p-4">
      <Text>Text 提供统一的主题颜色、字号与字重。</Text>
      <Text className="mt-2 text-sm text-muted-foreground">未传变体属性时使用正文默认样式。</Text>
    </View>
  );
};

export { TextBasic };

何时使用

应用内的所有文本都用它，而不是直接用 RN 的 Text —— 否则拿不到主题色与上下文继承。
需要「展开 / 收起」的多行折叠文本用 TextEllipsis。

字号

size 共十二档，其中 md 与 base 都映射到基础字号：

size	类名	size	类名
`4xs`	`text-4xs`	`base`	`text-base`
`3xs`	`text-3xs`	`md`	`text-base`
`2xs`	`text-2xs`	`lg`	`text-lg`
`xs`	`text-xs`	`xl`	`text-xl`
`sm`	`text-sm`	`2xl`	`text-2xl`
		`3xl`	`text-3xl`
		`4xl`	`text-4xl`

TextSize.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextSize = () => {
  return (
    <View className="gap-2 bg-background p-4">
      <Text size="4xs">4xs · 辅助标记</Text>
      <Text size="3xs">3xs · 微型文字</Text>
      <Text size="2xs">2xs · 紧凑说明</Text>
      <Text size="xs">xs · 辅助信息</Text>
      <Text size="sm">sm · 次要正文</Text>
      <Text size="md">md · 默认正文</Text>
      <Text size="base">base · 基础字号（与 md 相同）</Text>
      <Text size="lg">lg · 强调正文</Text>
      <Text size="xl">xl · 小标题</Text>
      <Text size="2xl">2xl · 区块标题</Text>
      <Text size="3xl">3xl · 页面标题</Text>
      <Text size="4xl">4xl · 展示标题</Text>
    </View>
  );
};

export { TextSize };

字重

weight 支持 normal / medium / semibold / bold。

TextWeight.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextWeight = () => {
  return (
    <View className="gap-3 bg-background p-4">
      <Text weight="normal">Normal · 常规正文</Text>
      <Text weight="medium">Medium · 中等强调</Text>
      <Text weight="semibold">Semibold · 次级标题</Text>
      <Text weight="bold">Bold · 重点标题</Text>
    </View>
  );
};

export { TextWeight };

语义颜色

color 提供 9 种语义色，全部取自主题 token，随浅色 / 深色模式自动切换：

颜色	类名
`foreground`	`text-foreground`
`muted`	`text-muted-foreground`
`primary`	`text-primary`
`secondary`	`text-secondary`
`destructive`	`text-destructive`
`success`	`text-success`
`warning`	`text-warning`
`info`	`text-info`
`accent`	`text-accent`

TextColor.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextColor = () => {
  return (
    <View className="gap-3 bg-background p-4">
      <Text color="foreground">Foreground · 默认前景色</Text>
      <Text color="muted">Muted · 次要信息</Text>
      <Text color="primary">Primary · 品牌强调</Text>
      <Text color="secondary">Secondary · 次级内容</Text>
      <Text color="success">Success · 成功状态</Text>
      <Text color="warning">Warning · 警告状态</Text>
      <Text color="destructive">Destructive · 危险状态</Text>
      <Text color="info">Info · 信息状态</Text>
      <Text color="accent">Accent · 强调内容</Text>
    </View>
  );
};

export { TextColor };

组合变体

三组变体相互独立，可以任意组合。

TextCombination.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextCombination = () => {
  return (
    <View className="gap-3 bg-background p-4">
      <Text
        color="primary"
        size="2xl"
        weight="bold"
      >
        2xl + bold + primary
      </Text>
      <Text
        color="success"
        size="sm"
        weight="medium"
      >
        sm + medium + success
      </Text>
    </View>
  );
};

export { TextCombination };

上下文样式继承

放在 Button、Cell 这类组件里的 Text 会通过 TextClassContext 继承父级下发的文字样式；显式传变体仍然能覆盖继承值。

TextContext.tsx

Loading…

import { Button, Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextContext = () => {
  return (
    <View className="gap-3 bg-background p-4">
      <Button color="destructive">
        <Text>未传文字变体，继承按钮样式</Text>
      </Button>
      <Button
        color="primary"
        variant="tonal"
      >
        <Text
          color="warning"
          weight="bold"
        >
          显式 color / weight 覆盖继承值
        </Text>
      </Button>
    </View>
  );
};

export { TextContext };

样式的合并优先级是：兜底样式 < 父级继承（Context）< 显式变体 props < className。

兜底样式（text-foreground text-base font-normal）刻意与变体表分开写，没有放进 defaultVariants —— 否则不传任何变体时变体表也会吐出基础类，反过来盖掉从 Context 继承的父级样式。

自定义组件想给子 Text 下发样式时，同样用这个 Context：

import { Text, TextClassContext } from '@skyroc/native-ui';

<TextClassContext value="text-sm text-muted-foreground">{children}</TextClassContext>;

自定义样式

className 排在最后参与合并，优先级高于所有变体。

TextStyles.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { View } from 'react-native';

const TextStyles = () => {
  return (
    <View className="gap-3 bg-background p-4">
      <Text
        className="text-warning"
        color="primary"
      >
        color 设置为 primary，className 覆盖为 warning
      </Text>
      <Text className="text-xl font-bold tracking-wide text-info">通过 className 自定义字号、字重与字距</Text>
    </View>
  );
};

export { TextStyles };

原生文字属性透传

numberOfLines、selectable、onPress、ellipsizeMode 等 RN Text 属性都会透传到底层节点。

TextNativeProps.tsx

Loading…

import { Text } from '@skyroc/native-ui';
import { useState } from 'react';
import { View } from 'react-native';

const TextNativeProps = () => {
  const [pressCount, setPressCount] = useState(0);

  return (
    <View className="gap-3 bg-background p-4">
      <Text
        className="max-w-64"
        numberOfLines={1}
      >
        这是一段会在单行末尾自动省略的较长文字，用于验证 numberOfLines 属性。
      </Text>
      <Text
        selectable
        className="text-muted-foreground"
      >
        selectable：长按可选择并复制这段文字
      </Text>
      <Text
        className="font-medium text-primary"
        onPress={() => setPressCount(prev => prev + 1)}
      >
        onPress：已点击 {pressCount} 次
      </Text>
    </View>
  );
};

export { TextNativeProps };

组件固定了 allowFontScaling={false} 与 maxFontSizeMultiplier={1}，文字不随系统字体缩放变化 —— 但这两项写在 {...rest} 之前，需要跟随系统字号时可以自行传回来覆盖。

API

Text

除下表外，Text 透传 React Native Text 的全部属性（numberOfLines、selectable、onPress、testID 等）。

属性	说明	类型	默认值
color	语义文字色	'foreground' \| 'muted' \| 'primary' \| 'secondary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'accent'	-
size	字号，md 与 base 等价	'4xs' \| '3xs' \| '2xs' \| 'xs' \| 'sm' \| 'base' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'	-
weight	字重	'normal' \| 'medium' \| 'semibold' \| 'bold'	-
asChild	作为插槽渲染，把样式与属性合并到唯一的子元素上（@rn-primitives 组合模式）	boolean	false
className	文字类名，优先级高于全部变体	string	-
ref	底层 Text 的 ref；asChild 时转发到被插槽替换的子元素	Ref<Text>	-

不传 color / size / weight 时组件不会输出对应的类名，从而让 TextClassContext 的继承值生效 —— 这也是它们没有默认值的原因。

类型

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

TextProps 继承 RN 的 TextProps 并加上上表的变体属性。包内还导出了 textVariants、textBaseClass 与 TextClassContext。