xtf-text

组件说明

xtf-text 是文本组件，覆盖从展示型标题到微文案、从富文本到可复制/可编辑/可展开省略的全场景文本呈现。支持 display / title / h1~h4 / body / caption / micro / label 多级排版、8 种语义色、渐变/微光/辉光特效、单多行省略展开、富文本渲染以及链接跳转，是展示层文字排版的核心组件。

基础用法

1. 最简示例

通过 text 设置文本内容，level 控制排版层级，color 控制语义色：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <xtf-text level="title" text="这是一个标题" />
    <xtf-text text="这是一段正文内容，用于展示组件库的默认排版风格。" />
    <xtf-text level="caption" color="secondary" text="这是辅助说明文字" />
  </view>
</template>

2. 排版层级

通过 level 切换 display / title / h1~h4 / body / caption / micro / label 各层级：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 20rpx; padding: 32rpx">
    <xtf-text level="display" text="Display 大标题" />
    <xtf-text level="title" text="Title 标题" />
    <xtf-text level="h1" text="H1 标题" />
    <xtf-text level="h2" text="H2 标题" />
    <xtf-text level="body" text="Body 正文" />
    <xtf-text level="caption" text="Caption 说明" />
    <xtf-text level="micro" text="Micro 微文案" />
    <xtf-text level="label" text="Label 标签" />
  </view>
</template>

3. 语义色与强调效果

通过 color 切换语义色，通过 bold / underline / delete-line 添加文字强调：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 20rpx; padding: 32rpx">
    <xtf-text text="主要色文字" color="primary" />
    <xtf-text text="成功色文字" color="success" />
    <xtf-text text="警告色文字" color="warning" />
    <xtf-text text="危险色文字" color="danger" />
    <xtf-text text="加粗文字" bold />
    <xtf-text text="下划线文字" underline />
    <xtf-text text="删除线文字" delete-line />
    <xtf-text text="渐变文字" gradient />
  </view>
</template>

4. 多行省略与展开

通过 lines 设置省略行数，ellipsis-expandable 支持点击展开全文：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx; padding: 32rpx">
    <xtf-text
      :lines="2"
      ellipsis-expandable
      @expand="onExpand"
      @collapse="onCollapse"
      text="这是一段会被省略为两行的长文本内容，用于演示文本省略与展开交互。当用户点击该文本时，如果处于折叠状态则会展开全部内容，再次点击则恢复折叠。"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onExpand(e) {
      console.log('展开全文', e)
      uni.showToast({ title: '已展开', icon: 'none' })
    },
    onCollapse(e) {
      console.log('收起全文', e)
    }
  }
}
</script>

5. 可复制文本

通过 copyable 开启复制模式，复制成功触发 copy 事件：

vue

<template>
  <view style="padding: 32rpx">
    <xtf-text copyable text="https://ext.dcloud.net.cn/publisher?id=806400" @copy="onCopy" />
  </view>
</template>

<script>
export default {
  methods: {
    onCopy(content) {
      console.log('复制内容:', content)
      uni.showToast({ title: '复制成功', icon: 'success' })
    }
  }
}
</script>

6. 可编辑文本

通过 editable 开启编辑模式，配合 v-model:edit-value 双向绑定，失焦/回车触发 change / confirm 事件：

vue

<template>
  <view style="padding: 32rpx">
    <xtf-text
      editable
      :edit-value="name"
      @update:edit-value="name = $event"
      @change="onChange"
      @confirm="onConfirm"
    />
  </view>
</template>

<script>
export default {
  data() {
    return { name: '点击我编辑' }
  },
  methods: {
    onChange(val) {
      console.log('输入中:', val)
    },
    onConfirm(val) {
      console.log('确认编辑:', val)
      uni.showToast({ title: '已保存: ' + val, icon: 'none' })
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`text`	`String`	`''`	文本内容（使用默认插槽时可不传）	纯文本场景
`nodes`	`Array \| String`	`''`	富文本节点，传入后自动使用 `rich-text` 渲染	富文本/图文混排
`level`	`String`	`'body'`	排版层级：`'display'` / `'title'` / `'h1'`~`'h4'` / `'body'` / `'caption'` / `'micro'` / `'label'`	控制文字大小
`color`	`String`	`''`	语义色：`'primary'` / `'secondary'` / `'success'` / `'warning'` / `'danger'` / `'disabled'` / `'link'` / `'inverse'`	控制文字颜色
`align`	`String`	`'left'`	对齐方式：`'left'` / `'center'` / `'right'`	排版对齐
`lines`	`Number \| String`	`0`	省略行数，`0` 不省略，`1` 单行省略，`>1` 多行省略	长文本截断
`indent`	`Boolean`	`false`	首行缩进两字符	段落排版
`gradient`	`Boolean`	`false`	渐变文字效果	品牌强调
`shimmer`	`Boolean`	`false`	微光闪烁效果	装饰文案
`glow`	`Boolean`	`false`	辉光发光效果	强调标题
`underline`	`Boolean`	`false`	下划线	强调文字
`deleteLine`	`Boolean`	`false`	删除线	原价/废弃文案
`bold`	`Boolean`	`false`	加粗	强调文字
`block`	`Boolean`	`true`	是否块级显示	独占一行
`selectable`	`Boolean`	`false`	文字是否可长按选中	复制场景
`space`	`String`	`''`	空格显示策略（原生 `text` space 属性）	特殊空格
`decode`	`Boolean`	`false`	是否解码 HTML 实体	特殊字符
`clickable`	`Boolean`	`true`	是否可点击（触发 `click`/`tap`）	交互文字
`copyable`	`Boolean`	`false`	是否显示复制图标，点击复制文本	复制场景
`editable`	`Boolean`	`false`	是否可编辑，点击进入编辑态	行内编辑
`editValue`	`String`	`''`	编辑态初始值（`v-model:edit-value`）	行内编辑
`editPlaceholder`	`String`	`'请输入内容'`	编辑态占位符	行内编辑
`editMaxlength`	`Number \| String`	`0`	编辑最大长度，`0` 不限	限制输入
`href`	`String`	`''`	链接跳转 URL（H5 `window.open` / 小程序 `navigateTo`）	链接文本
`ellipsisExpandable`	`Boolean`	`false`	省略号点击展开全文（配合 `lines`）	展开交互
`ellipsisTooltip`	`Boolean`	`false`	省略号 tooltip（H5 生效）	悬停提示
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`click`	点击文本时触发（`clickable` 为真且非省略展开/链接跳转场景）	`(event)`	点击事件对象
`tap`	同 `click`	`(event)`	点击事件对象
`longpress`	长按文本时触发	`(event)`	原生长按事件对象
`copy`	点击复制图标复制成功时触发	`(content: String)`	被复制的内容
`expand`	`ellipsis-expandable` 下点击展开全文时触发	`(event)`	点击事件对象
`collapse`	展开状态下点击收起时触发	`(event)`	点击事件对象
`change`	编辑态输入变化时触发	`(value: String)`	当前输入内容
`blur`	编辑态失焦时触发	`(value: String)`	失焦时的内容
`confirm`	编辑态按回车确认时触发	`(value: String)`	确认时的内容
`update:editValue`	编辑态输入时同步更新 `editValue`	`(value: String)`	当前输入内容

事件使用示例

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-text clickable text="点击我（click 事件）" @click="onClick" @longpress="onLongPress" />
    <xtf-text copyable text="复制这段文字" @copy="onCopy" />
    <xtf-text
      :lines="1"
      ellipsis-expandable
      text="长文本展开收起示例，点击触发 expand / collapse 事件。"
      @expand="onExpand"
      @collapse="onCollapse"
    />
    <xtf-text editable :edit-value="editText" @change="onEditChange" @confirm="onEditConfirm" />
  </view>
</template>

<script>
export default {
  data() {
    return { editText: '点击编辑' }
  },
  methods: {
    onClick(e) {
      console.log('click', e)
      uni.showToast({ title: '点击了文本', icon: 'none' })
    },
    onLongPress(e) {
      console.log('longpress', e)
      uni.showToast({ title: '长按了文本', icon: 'none' })
    },
    onCopy(content) {
      console.log('copy', content)
      uni.showToast({ title: '已复制', icon: 'success' })
    },
    onExpand(e) {
      console.log('expand', e)
    },
    onCollapse(e) {
      console.log('collapse', e)
    },
    onEditChange(val) {
      console.log('change', val)
      this.editText = val
    },
    onEditConfirm(val) {
      console.log('confirm', val)
      uni.showToast({ title: '保存:' + val, icon: 'none' })
    }
  }
}
</script>

插槽

插槽名称	说明
`default`	文本内容（有 `text` 属性时默认插槽优先）

插槽使用示例

默认插槽可在 text 基础上插入富内容，例如组合图标与文字：

vue

<template>
  <view style="padding: 32rpx">
    <xtf-text level="title" color="primary">
      <xtf-icon name="star" size="md" style="margin-right: 8rpx" />
      带图标的标题文字
    </xtf-text>
  </view>
</template>

<script>
export default {
  methods: {}
}
</script>

主题说明

正文颜色使用 var(--xtf-text-body-color)，标题颜色使用 var(--xtf-text-heading-color)
正文字体使用 var(--xtf-font-font-family-base)，标题字体使用 var(--xtf-font-font-family-title)
渐变文字使用 var(--xtf-text-gradient-primary-start) / var(--xtf-text-gradient-primary-end)
微光效果使用 var(--xtf-text-shimmer-start) / var(--xtf-text-shimmer-mid) / var(--xtf-text-shimmer-end)
辉光效果使用 var(--xtf-text-glow-primary)
链接文字颜色使用 var(--xtf-text-link-color)
字号使用 --xtf-font-font-size-* 系列变量，行高使用 --xtf-font-line-height-* 系列变量

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-text ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 排版层级 ​

3. 语义色与强调效果 ​

4. 多行省略与展开 ​

5. 可复制文本 ​

6. 可编辑文本 ​

全部属性 ​

事件 ​

事件使用示例 ​

插槽 ​

插槽使用示例 ​

主题说明 ​