更新记录

1.0.0（2026-09-18）

nurzil-text 原生渐变文字

独立实现的 uni-app x 标准模式原生组件，面向 HBuilderX 5.24 蒸汽模式。参考 lime-gradient-text 的公开功能说明，未使用其收费源码，不依赖 lime-shared。

Android 使用 TextView + Shader，iOS 使用 UILabel + CAGradientLayer 遮罩，鸿蒙使用 ArkUI Text + 离屏渐变合成。完整字符串交给原生文字引擎排版，不逐字拆开；支持维吾尔语连写、自定义字体、多行和 RTL。

使用

<template>
  <nurzil-text
    class="title-gradient"
    text="美丽的渐变文字"
    type="linear"
    :deg="90"
    :colors="['#ff669d', '#ffc36b', '#73e6d2']"
    :font-size="30"
    direction="ltr"
    text-align="center"
  />
</template>

<style>
  .title-gradient {
    width: 300px;
    height: 72px;
  }
</style>

支持 easycom；也可像演示页一样显式导入组件。插件不包含项目字体，font-path 指向使用方项目内的字体文件。

原生字体不会继承页面 .ug 或父级 CSS，必须通过 font-family / font-path 指定。建议同时传入字体文件路径，原生端会解析实际资源位置。仅支持项目代码包内的本地字体，不下载远程字体；不可用时回退字体。

属性

渐变以整个组件矩形为坐标范围。径向渐变以矩形中心为圆心，半对角线为半径；锥形渐变从顶部开始顺时针旋转。颜色八位格式统一使用 CSS 的末尾 alpha，不使用 Android 的 AARRGGBB 顺序。为减少多端差异，此版本不解析 CSS 渐变字符串、命名色或颜色位置对象，使用 colors + locations 配置。

组件默认宽度 100%、高度 64px。需要多行时必须增大组件高度；高度不足时内容会被裁剪。默认垂直居中，文字尺寸变化不会自动撑高 native-view。

事件和生命周期

• load：初始化调用已提交，不表示首帧已绘制或字体加载已验证。
• error(message)：参数校验或原生实例创建调用失败。无效更新保留之前的原生画面。
• 属性变化更新同一个原生实例；卸载自动销毁，避免重复绑定。
• 不申请权限、不发起网络请求、不使用 WebView。

演示页

当前项目已注册 pages/gradient-demo/gradient-demo，包含三种渐变、自定义色标、UKIJEkran 维吾尔语、两行省略、切换配色和旋转角度。可在 HBuilderX 中将该页作为运行页面。未更改首页及业务页面的原有文字。

平台与验证

独立 lsp lint 因 HBuilderX 返回 Failed to read platform settings 未能执行，不等同于代码通过静态检查。Android 验证命令为 cli compile app-android --project <项目路径> --uni_module nurzil-text。

鸿蒙 auto 为首个方向字母判断，复杂双向控制符及不同基方向的多段文本应显式指定 direction。三端字体度量、换行和粗体效果由系统引擎决定，不保证像素级完全一致。

新增原生插件后需要重新编译 App；仅刷新 JS 热更资源不能替代原生插件集成。iOS 需完整 Xcode、可用 SDK 和签名基座或模拟器；鸿蒙需配置 DevEco Studio 与可用 SDK。

回归

项目 tests/gradient-text.test.cjs 覆盖参数、色标、生命周期、动态更新和模板解析。执行 node tests/gradient-text.test.cjs。这是本地逻辑验证，不能替代三平台原生编译或字体视觉验证。

实现依据

• DCloud native-view 文档：“需要开发者监听 @init 事件，在此事件中创建平台原生 view 与 UniNativeViewElement 进行绑定”。
• 标准模式组件文档：“绑定原生 view 方法……仅支持调用一次”；“iOS 平台需要 Vue 组件主动释放 UTS 实例”。
• 原生混编文档：各平台目录可以放 Kotlin、Swift、ArkTS，UTS 入口负责调用原生实现。

平台兼容性

uni-app x(5.24)

nurzil-text 原生渐变文字

独立实现的 uni-app x 标准模式原生组件，面向 HBuilderX 5.24 蒸汽模式。参考 lime-gradient-text 的公开功能说明，未使用其收费源码，不依赖 lime-shared。

Android 使用 TextView + Shader，iOS 使用 UILabel + CAGradientLayer 遮罩，鸿蒙使用 ArkUI Text + 离屏渐变合成。完整字符串交给原生文字引擎排版，不逐字拆开；支持维吾尔语连写、自定义字体、多行和 RTL。

使用

<template>
  <nurzil-text
    class="title-gradient"
    text="美丽的渐变文字"
    type="linear"
    :deg="90"
    :colors="['#ff669d', '#ffc36b', '#73e6d2']"
    :font-size="30"
    direction="ltr"
    text-align="center"
  />
</template>

<style>
  .title-gradient {
    width: 300px;
    height: 72px;
  }
</style>

支持 easycom；也可像演示页一样显式导入组件。插件不包含项目字体，font-path 指向使用方项目内的字体文件。

原生字体不会继承页面 .ug 或父级 CSS，必须通过 font-family / font-path 指定。建议同时传入字体文件路径，原生端会解析实际资源位置。仅支持项目代码包内的本地字体，不下载远程字体；不可用时回退字体。

属性

渐变以整个组件矩形为坐标范围。径向渐变以矩形中心为圆心，半对角线为半径；锥形渐变从顶部开始顺时针旋转。颜色八位格式统一使用 CSS 的末尾 alpha，不使用 Android 的 AARRGGBB 顺序。为减少多端差异，此版本不解析 CSS 渐变字符串、命名色或颜色位置对象，使用 colors + locations 配置。

组件默认宽度 100%、高度 64px。需要多行时必须增大组件高度；高度不足时内容会被裁剪。默认垂直居中，文字尺寸变化不会自动撑高 native-view。

事件和生命周期

• load：初始化调用已提交，不表示首帧已绘制或字体加载已验证。
• error(message)：参数校验或原生实例创建调用失败。无效更新保留之前的原生画面。
• 属性变化更新同一个原生实例；卸载自动销毁，避免重复绑定。
• 不申请权限、不发起网络请求、不使用 WebView。

演示页

当前项目已注册 pages/gradient-demo/gradient-demo，包含三种渐变、自定义色标、UKIJEkran 维吾尔语、两行省略、切换配色和旋转角度。可在 HBuilderX 中将该页作为运行页面。未更改首页及业务页面的原有文字。

平台与验证

独立 lsp lint 因 HBuilderX 返回 Failed to read platform settings 未能执行，不等同于代码通过静态检查。Android 验证命令为 cli compile app-android --project <项目路径> --uni_module nurzil-text。

鸿蒙 auto 为首个方向字母判断，复杂双向控制符及不同基方向的多段文本应显式指定 direction。三端字体度量、换行和粗体效果由系统引擎决定，不保证像素级完全一致。

新增原生插件后需要重新编译 App；仅刷新 JS 热更资源不能替代原生插件集成。iOS 需完整 Xcode、可用 SDK 和签名基座或模拟器；鸿蒙需配置 DevEco Studio 与可用 SDK。

回归

项目 tests/gradient-text.test.cjs 覆盖参数、色标、生命周期、动态更新和模板解析。执行 node tests/gradient-text.test.cjs。这是本地逻辑验证，不能替代三平台原生编译或字体视觉验证。

实现依据

• DCloud native-view 文档：“需要开发者监听 @init 事件，在此事件中创建平台原生 view 与 UniNativeViewElement 进行绑定”。
• 标准模式组件文档：“绑定原生 view 方法……仅支持调用一次”；“iOS 平台需要 Vue 组件主动释放 UTS 实例”。
• 原生混编文档：各平台目录可以放 Kotlin、Swift、ArkTS，UTS 入口负责调用原生实现。