更新记录

1.0.1（2026-01-16）

截图

1.0.0（2026-01-16）

• feat: 初版支持 iOS/Android 线性/径向渐变容器
• docs: 补充组件文档与使用说明

平台兼容性

uni-app x(4.87)

hans-gradient-view

uni-app x 原生渐变容器组件（iOS / Android），支持线性渐变与径向渐变。

特性

• 原生渲染：iOS 使用 CGGradient 自绘，Android 使用 LinearGradient/RadialGradient 自绘
• 渐变在底层，内容通过 slot 叠加在上层（适合作为卡片背景/按钮背景）
• 支持圆角裁剪

平台支持

• uni-app x -> app-ios ✅
• uni-app x -> app-android ✅

用法

<hans-gradient-view
    style="width: 300px; height: 160px;"
    :type="'linear'"
    :colors="['#ff7a18', '#af002d', '#319197']"
    :locations="[0, 0.5, 1]"
    :startX="0"
    :startY="0"
    :endX="1"
    :endY="1"
    :cornerRadius="16"
>
    <view style="padding: 16px;">
        <text style="color: rgba(255,255,255,0.92); font-size: 18px;">Gradient</text>
    </view>
</hans-gradient-view>

径向渐变示例（start 为中心点，end 只用来计算半径）：

<hans-gradient-view
    style="width: 300px; height: 160px;"
    :type="'radial'"
    :colors="['#00c6ff', '#0072ff']"
    :locations="[0, 1]"
    :startX="0.5"
    :startY="0.5"
    :endX="1"
    :endY="0.5"
    :cornerRadius="16"
/>

Slots

• 默认插槽：前景内容（显示在渐变层之上）

Props

• type: "linear" | "radial"（默认 "linear"）
• colors: 颜色数组（默认 ['#ff7a18', '#af002d', '#319197']；建议 >=2；跨端一致的推荐格式：#RGB/#RRGGBB/#RRGGBBAA/rgb()/rgba()/transparent）
• locations: 0~1 的 stop 数组（可选；默认 []；数量需与 colors 一致，不一致时会被忽略）
• startX/startY/endX/endY: 0~1 的归一化坐标（默认 0.5/0/0.5/1）
  • linear: 起点/终点为渐变方向
  • radial: start 为中心点，end 为半径点（半径 = start→end 距离）
• cornerRadius: 圆角（px，默认 0）

Events

• ready: 原生视图初始化完成

Methods

• refresh()：手动刷新配置（例如在外部尺寸/内容变化后触发）

说明

• 组件需要有明确的宽高（例如通过 style / class 设置），否则高度为 0 时看不到渐变。
• 如果原生视图初始化失败，会自动降级为纯色背景（使用 colors[0]）。
• 颜色数组为空时会降级为透明；仅传 1 个颜色时会自动复制为两端同色。
• 组件内部会把 colors/locations 数组序列化为 | 分隔字符串，业务侧无需手动拼接。