HumanBreak/docs/api/motajs-render-vue/GraphicBaseProps.md

GraphicBaseProps API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

接口定义

interface GraphicBaseProps extends BaseProps {
    /** 是否填充（默认 false） */
    fill?: boolean;
    /** 是否描边（默认 false） */
    stroke?: boolean;
    /** 强制先描边后填充（优先级最高，默认 false） */
    strokeAndFill?: boolean;
    /** 填充规则（默认 "evenodd"） */
    fillRule?: CanvasFillRule;
    /** 填充样式（颜色/渐变/图案） */
    fillStyle?: CanvasStyle;
    /** 描边样式（颜色/渐变/图案） */
    strokeStyle?: CanvasStyle;
    /** 交互时是否仅检测描边区域（默认 false） */
    actionStroke?: boolean;
}

---

核心属性说明

属性	类型	默认值	说明
fill	boolean	false	启用填充（需设置 fillStyle）
stroke	boolean	false	启用描边（需设置 strokeStyle 和 strokeWidth）
strokeAndFill	boolean	false	强制先描边后填充（覆盖 fill 和 stroke 的设置）
fillRule	"nonzero" | "evenodd"	"evenodd"	填充路径计算规则（影响复杂图形的镂空效果）
fillStyle	string | CanvasGradient | CanvasPattern	-	填充样式（支持 CSS 颜色、渐变对象等）
strokeStyle	string | CanvasGradient | CanvasPattern	-	描边样式
actionStroke	boolean	false	设为 true 时，交互事件仅响应描边区域（需配合 stroke 使用）

---

使用示例（以矩形为例）

示例 1：仅填充模式

<g-rect
    loc={[100, 100, 200, 150]} // x,y,width,height
    fill
    fillStyle="#fff"
/>

效果：

• 200x150 矩形
• 无描边效果

---

示例 2：仅描边模式

<g-rect
    loc={[400, 200, 180, 120]}
    stroke
    strokeStyle="rgba(0,0,0,0.8)"
    strokeWidth={4}
    actionStroke // 点击时仅描边区域响应
/>

交互特性：

• 4px 黑色半透明描边
• 鼠标悬停在描边区域才会触发事件

---

示例 3：填充 + 描边（默认顺序）

<g-rect
    loc={[50, 300, 150, 100]}
    fill
    stroke
    fillStyle="#ffe66d"
    strokeStyle="#2d3436"
    strokeWidth={2}
/>

渲染顺序：

1. 填充黄色背景
2. 在填充层上绘制黑色描边

---

示例 4：强制先描边后填充

<g-rect
    loc={[300, 400, 200, 200]}
    strokeAndFill
    fillStyle="#a29bfe"
    strokeStyle="#6c5ce7"
    strokeWidth={8}
/>

渲染顺序：

1. 绘制紫色描边
2. 在描边层上填充浅紫色
   视觉效果：描边被填充色覆盖一部分

---

最佳实践

交互增强技巧

import { ref } from 'vue';

// 高亮描边交互反馈
const hovered = ref(false);
// 使用 void 关键字屏蔽返回值，避免返回值泄漏
const enter = () => void (hovered.value = true);
const leave = () => void (hovered.value = false);

<g-rect
    loc={[100, 100, 200, 80]}
    fill
    fillStyle="#ffffff"
    stroke={hovered.value}
    strokeStyle="#e84393"
    strokeWidth={3}
    onEnter={enter}
    onLeave={leave}
/>;

---

注意事项

1. 样式覆盖顺序：
   strokeAndFill 会强制按 描边 → 填充 顺序渲染，忽略 fill 和 stroke 的独立设置。

2. 路径闭合规则：
   fillRule="evenodd" 适用于以下场景：

   // 五角星镂空效果
   <path
       fill={true}
       fillRule="evenodd"
       path={starPath} // 交替重叠的路径
   />
   

3. 性能问题： 多数情况下，图形的性能很好，不需要单独优化，但是如果你使用 path 标签，且内容复杂，建议添加 cache 属性来启用缓存，避免频繁的复杂图形绘制。