Text 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

统一展示文本，支持排版与截断，适合正文、标签和受限空间中的信息表达。

使用选择

用于文本语义、截断、展开和提示。默认不启用 hover 动效；静态普通文字可使用语义 HTML，动态数值或文字过渡按动效组件选择。

• tag 指定文本语义，lines 控制截断，more / tooltip 提供展开与补充提示。

• 默认不启动 hover 交互；stateText 可按状态替换文字，parts 配置默认 Button / Tooltip。

• lines=1 缩短可见文字时仍保留完整可访问名称；用于按钮、链接或原生标签时不丢失名称尾部。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Text, Button, Frame } from '@snowui-design-system/components';</script> <div style="width: min(100%, 24rem); min-width: 0;">	<Text lines={1} tooltip style="font-size: var(--text-14); line-height: var(--leading-14); width: 100%;">Design system documentation — component behavior, accessibility, and release notes</Text></div>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

内置组件双模式

• parts.Button：配置 lines=0 + more 生成的内置展开按钮。

• parts.Tooltip：配置截断时内置 Tooltip。

• 外置 Tooltip 或其他 children 不受 Text 私有 DOM 选择器控制。

继承: 复用 Frame.svelte 的所有通用能力 (交互、动效、响应式、形态等)。 默认能力开关: enableResponsive=false, enableContext=true, enableScaleObserver=false。 核心机制: 采用 组件内聚模式 (Component-owned Truncation)，Text 自身直接处理 lines/onTruncate，Frame 仅负责通用能力路由。

未声明 lines 时，截断控制器保持休眠，不读取文本、不排队 rAF，也不登记 MutationObserver / ResizeObserver；动态设置 lines 后再按既有协议激活，不改变默认文本视觉。

布局模型

主布局模型：文本流布局。

• Text 的主职责是保留 HTML 文本流、语义 tag、截断和 tooltip/more 角色定位，不参与槽位宿主、内联外壳或复合管理布局注册。

• tag 决定 block / inline-block / list-item / code 等文本流显示模式；lines=0/1/2/3 只改变截断和遮罩，不改变组件的主布局模型。

• <Tooltip as="tooltip"> 与 <Button as="more"> 是 Text 内的角色子项：Tooltip 负责截断提示，Button 仍按 Button 的内联外壳布局渲染。

• Text 不使用 padding/gap 管理内部排列，也不通过 margin 改变外部文本流间距；交互位移只能走 transform 变量。

1.1 功能概览

• 智能截断: Text 直接支持 lines={0|1|2|3} 和 onTruncate；单行模式复用 fitTextToElement()，稳定显示紧跟文字的显式省略符。

• 全文可访问: 单行截断时，可见短文本只负责视觉；复用现有fullText与包内无障碍隐藏样式提供完整纯文本，避免父Button、链接或原生标签的名称只剩截断前缀。不重复渲染交互Snippet，也不新增测量器。

• 内置展开: lines=0 时可通过 more 开启内置 ArrowLineDown Button，默认关闭；内置按钮默认开启与 BarChart 模糊浮层一致的背景模糊。

• 滚动模式: lines=0 未显示 more 按钮时，内容使用 Textarea 同源的上下渐隐与浮层滚动条；显示 more 时改为展开模式且不渲染滚动条。

• 角色化组合:

  • <Tooltip as="tooltip">: 截断时自动显示的提示。

  • <Button as="more">: "展开/收起" 按钮。

• 响应式: tag / class 可通过 responsive 进行断点覆写。

• 动效: 继承 Frame 的所有动效触发器 (whileHover, whileClick 等)。

1.2 关键字定义 (Keywords)

stateText 解析规则

1. Text 读取最近父级 Frame Context 的 currentState。

2. 当前状态命中 stateText[currentState] 时渲染该文本。

3. 未命中当前状态时回退 stateText.Idle。

4. 未传 stateText 或仍未解析出文本时继续渲染 children。

5. stateText 只用于同结构文本替换,不承载复杂 DOM。复杂自定义子树仍属于 stateContent 的例外场景。

Load 是 Frame loading / skeleton 协议状态名。若只是按钮任务处理中并需要展示真实文案,优先使用 Pending。

1.3 使用示例

 <Text>普通文本，无截断。</Text>  <Text lines={1}>Very long text that will be truncated...</Text>  <Text lines={1}>    Very long text that will be truncated...    <Tooltip as="tooltip">完整的很长的文本内容...</Tooltip></Text>  <Text lines={3}>长段落将被截断为3行...</Text>  <Text lines={0} class="bg-black-5 p-4 rounded-8">    很长的内容可以展开查看...    <Button as="more" variant="borderless" class="text-blue">        展开全文    </Button></Text>  <Text lines={0} more>    很长的内容可以展开查看。</Text>  <Text lines={0} style="height: 5rem;">    很长的内容可以在约束高度内滚动查看。</Text>  <Text    lines={1}    enableResponsive    class="text-12"    responsive={{        sm: { class: "text-14" },        lg: { class: "text-16" }    }}>    响应式文本...</Text>  <Button Click="Active" Active={["Idle", "auto"]} whileActive={{ duration: 2000 }}>    <Icon stateIcon={{ Idle: Paperclip, Active: Check }} />    <Text stateText={{ Idle: "复制", Active: "已复制" }} /></Button>  <Button    Click={{ Idle: "Pending", Active: "Idle" }}    Pending={["Active", "auto"]}>    <Icon stateIcon={{ Idle: null, Pending: Spinner, Active: Check }} />    <Text stateText={{ Idle: "Ready", Pending: "Loading...", Active: "Completed" }} /></Button>

1. 基础样式

2. 布局模式 (Layout Modes)

3. Hover 交互

默认关闭；仅在 interactive === true 时生效：

5. 截断与可展开样式 (lines=0/2/3)