更新记录

1.0.0（2026-10-19） 下载此版本

已验证安卓和鸿蒙系统

平台兼容性

uni-app x(3.8.6)

其他

djiz-radial-gradient

uni-app x 渐变容器组件插件。uni-app x 的 App 原生端不支持 CSS radial-gradient（linear-gradient 也不稳定），本插件通过各端原生能力自绘径向 + 线性渐变，并封装为可直接在模板中使用的容器组件。

平台支持

特性

• 径向（radial）+ 线性（linear）双渐变类型
• 多色标渐变，色标位置可控
• 径向：圆心位置可偏移、半径可调、支持圆形/椭圆
• 线性：起终点归一化坐标任意定义方向
• 支持圆角裁剪（圆角矩形、正圆）
• 参数动态更新立即生效
• 容器组件，内部可放置任意内容（默认插槽）

使用方式

easycom 自动引入，无需手动 import：

<!-- 径向（默认） -->
<djiz-radial-gradient
  style="width: 300rpx; height: 300rpx;"
  :colors="['#FF6B6B', '#5B8DEF']"
>
  <text style="color: #FFFFFF; margin: auto;">内容</text>
</djiz-radial-gradient>

<!-- 线性 -->
<djiz-radial-gradient
  style="width: 500rpx; height: 300rpx;"
  type="linear"
  :colors="['#4FACFE', '#00F2FE']"
  :start-x="0" :start-y="0" :end-x="1" :end-y="1"
></djiz-radial-gradient>

Props

Events

监听 error 做联动的示例：

<djiz-radial-gradient
  :colors="['#1A2980', '#26D0CE']"
  fallback-color="#16215E"
  :border-radius="16"
  @error="onGradientError"
>
  <text :style="'margin:auto;color:'+(failed ? '#E8EAFF' : '#FFFFFF')">文字</text>
</djiz-radial-gradient>

const failed = ref<boolean>(false)
function onGradientError(reason: string) {
  failed.value = true
}

单位说明

• 组件宽高遵循 uvue 规范，可使用 px / rpx。
• radius 是相对对角线的比例值，与组件尺寸无关，跨尺寸效果一致。
• borderRadius 使用逻辑 px（CSS px），非 rpx。
• 线性渐变方向由 start→end 向量决定：默认 (0.5,0)→(0.5,1) 从上到下；(0,0)→(1,1) 为左上到右下对角线。

更多示例

<!-- 三色标 + 偏心 -->
<djiz-radial-gradient
  :colors="['#FF9A9E', '#A18CD1', '#FBC2EB']"
  :stops="[0, 0.55, 1]"
  :center-x="0.3"
  :center-y="0.25"
></djiz-radial-gradient>

<!-- 椭圆 -->
<djiz-radial-gradient shape="ellipse" :colors="['#FAD961', '#F76B1C']"></djiz-radial-gradient>

<!-- 圆角矩形 -->
<djiz-radial-gradient :border-radius="20" :colors="['#43E97B', '#38F9D7']"></djiz-radial-gradient>

<!-- 正圆 -->
<djiz-radial-gradient :border-radius="90" :colors="['#FA709A', '#FEE140']"></djiz-radial-gradient>

完整演示见项目页面：pages/radial-gradient-demo/demo.uvue。

实现原理

采用 UTS 标准模式组件（components/ 下跨端 uvue + utssdk/ 下各端原生实现），通过内置 native-view 组件承载原生视图：

• Android：混编 RadialGradientView.kt，径向用 RadialGradient、线性用 LinearGradient 构建 shader；椭圆通过给 shader 套以圆心为支点的缩放 Matrix；圆角通过 ViewOutlineProvider + clipToOutline（硬件加速）。
• iOS：CAGradientLayer，径向 type=radial、线性 type=axial（startPoint/endPoint 单位坐标系）；椭圆通过对齐锚点后的 CATransform3DMakeScale；圆角通过容器视图 cornerRadius + masksToBounds。
• 鸿蒙：builder.ets 使用 ArkUI 通用属性 .radialGradient() / .linearGradient()（API 11+），线性方向由 start/end 坐标转 angle；椭圆通过 .scale()；圆角通过 .borderRadius() + .clip()；实际布局尺寸由 onSizeChange 获取。

目录结构

djiz-radial-gradient/
├── components/djiz-radial-gradient/djiz-radial-gradient.uvue  # 跨端组件
├── utssdk/
│   ├── app-android/
│   │   ├── RadialGradientView.kt   # Android 自绘 View
│   │   └── index.uts
│   ├── app-ios/
│   │   └── index.uts
│   └── app-harmony/
│       ├── options.uts             # BuilderNode 参数
│       ├── builder.ets             # ArkUI 声明式实现
│       └── index.uts
└── package.json