文本 · Text

文本用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
文本 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
文本 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
文本 · 交互示例 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
文本 · 交互示例 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
文本 · 交互示例 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Text

Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1–h6 element.

属性	类型	默认值	说明
type	'body' \| 'large' \| 'label' \| 'supporting' \| 'code' \| 'display-1' \| 'display-2' \| 'display-3' \| 'inherit'	'body'	Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.
children *	ReactNode		Text content.
size	'4xs' \| '3xs' \| '2xs' \| 'xsm' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'		Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.
color	'primary' \| 'secondary' \| 'disabled' \| 'placeholder' \| 'accent' \| 'inherit'		Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.
weight	'normal' \| 'medium' \| 'semibold' \| 'bold'		Font weight override.
display	'inline' \| 'block'	'inline'	Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.
as	'span' \| 'p' \| 'div' \| 'label'	'span'	HTML element to render.
maxLines	number	0	Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.
hasTruncateTooltip	boolean \| 'above' \| 'below' \| 'start' \| 'end'	true	Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' \| 'below' \| 'start' \| 'end') sets a specific position.
wordBreak	'break-word' \| 'break-all'		Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.
textWrap	'wrap' \| 'nowrap' \| 'balance' \| 'pretty'		Text wrapping behavior.
justify	'start' \| 'center' \| 'end'	'start'	Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.
hasCapsize	boolean	false	Enable optical alignment using text-box-trim. Forces block display.
hasStrikethrough	boolean	false	Apply strikethrough text decoration.
hasTabularNumbers	boolean	false	Use tabular (monospace) numbers for aligned numeric data.
id	string		HTML id attribute.
xstyle	StyleXStyles		StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.

使用建议

Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.
Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.
Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.
Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.
避免：Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.
避免：Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.
避免：Use raw HTML tags like <p>, <h1>–<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.
避免：Pass a variant prop; Text does not have a variant prop. Use type for semantic styling (body, label, large, supporting, code) or use Heading for headings.
避免：Use Text for headings; use Heading with a level prop (1–6) for section titles and headings.

主题 API

{
  "targets": [
    {
      "className": "astryx-heading",
      "visualProps": [
        "level",
        "color",
        "type",
        "weight"
      ]
    },
    {
      "className": "astryx-text",
      "visualProps": [
        "type",
        "size",
        "color"
      ]
    }
  ]
}

Heading

组件结构

Text: Polymorphic text element that renders the supplied content with themed typography.
Heading: Referenced Heading member that renders the supplied content as a semantic h1–h6 element.
Truncation tooltip: Tooltip-owned surface available only when Text or Heading is measured as truncated and truncation tooltips are enabled.