Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

形状

Scripting 提供了一套形状组件，用于绘制可缩放的矢量图形元素，包括矩形、圆形、椭圆、胶囊形、圆角矩形等。这些图形支持填充、描边、裁剪路径和尺寸控制，可广泛应用于信息展示、装饰背景、自定义进度视图等界面场景。

通用属性：ShapeProps

所有形状组件均支持以下属性，用于控制外观：

1type ShapeProps = {
2  trim?: {
3    from: number
4    to: number
5  }
6  fill?: ShapeStyle | DynamicShapeStyle
7  stroke?: ShapeStyle | DynamicShapeStyle | {
8    shapeStyle: ShapeStyle | DynamicShapeStyle
9    strokeStyle: StrokeStyle
10  }
11  strokeLineWidth?: number // 已废弃
12}

属性说明

属性名 类型 说明
trim { from: number; to: number } 裁剪图形路径，仅绘制部分路径。from 与 to 为 0～1 的小数。
fill ShapeStyle 或 DynamicShapeStyle 设置填充颜色或渐变。
stroke 同 fill，或带 strokeStyle 的对象 设置描边颜色或渐变，支持自定义描边样式。
strokeLineWidth number（已废弃） 设置描边宽度。建议使用 stroke.strokeStyle.lineWidth 替代。

描边样式：StrokeStyle

你可以通过 strokeStyle 对象来自定义描边的线条细节：

1type StrokeStyle = {
2  lineWidth?: number
3  lineCap?: 'butt' | 'round' | 'square'
4  lineJoin?: 'bevel' | 'miter' | 'round'
5  mitterLimit?: number
6  dash?: number[]
7  dashPhase?: number
8}

描边样式参数说明

参数名 说明
lineWidth 描边线条的宽度（单位：pt）。
lineCap 线条端点样式，可选 "butt"（平头）、"round"（圆头）、"square"（方头）。
lineJoin 拐角连接样式，可选 "miter"、"round"、"bevel"。
mitterLimit miter 样式拐角的最小限制（用于防止尖角过长）。
dash 虚线样式数组，定义实线和空白的交替长度。
dashPhase 从虚线图案中的哪个位置开始绘制（偏移量）。

支持的形状组件

Rectangle 矩形

1<Rectangle
2  fill="orange"
3  stroke={{
4    shapeStyle: "red",
5    strokeStyle: {
6      lineWidth: 3,
7      lineJoin: "round"
8    }
9  }}
10  frame={{ width: 100, height: 100 }}
11/>

RoundedRectangle 圆角矩形

1<RoundedRectangle
2  fill="blue"
3  cornerRadius={16}
4  frame={{ width: 100, height: 100 }}
5/>

支持统一圆角半径或尺寸：

1type RoundedRectangleProps = ShapeProps & (
2  | { cornerRadius: number }
3  | { cornerSize: { width: number, height: number } }
4) & {
5  style?: RoundedCornerStyle // 默认为 continuous
6}

UnevenRoundedRectangle 不规则圆角矩形

支持为每个角设置不同的圆角半径：

1<UnevenRoundedRectangle
2  fill="brown"
3  topLeadingRadius={16}
4  topTrailingRadius={0}
5  bottomLeadingRadius={0}
6  bottomTrailingRadius={16}
7  frame={{ width: 100, height: 50 }}
8/>

Circle 圆形

1<Circle
2  stroke="purple"
3  strokeLineWidth={4}
4  frame={{ width: 100, height: 100 }}
5/>

Capsule 胶囊形

1<Capsule
2  fill="systemIndigo"
3  frame={{ width: 100, height: 40 }}
4/>

Ellipse 椭圆

1<Ellipse
2  fill="green"
3  frame={{ width: 40, height: 100 }}
4/>

使用建议

  • 使用 fill 和 stroke 可分别设置填充与描边样式，支持纯色与渐变；
  • 若需自定义描边样式（如虚线、线头、线角），应使用 stroke.strokeStyle；
  • strokeLineWidth 已废弃，建议统一使用 strokeStyle.lineWidth；
  • trim 属性可用于实现动画绘图、进度展示等场景；
  • 所有形状组件均支持 frame、padding、background 等布局修饰符，适合与其他组件组合使用。
大纲