图形

¥Graphics

图形 是一款强大而灵活的工具，用于渲染矩形、圆形、星形和自定义多边形等形状。它还可以通过组合多个基元来创建复杂形状，并支持渐变、纹理和蒙版等高级功能。

¥Graphics is a powerful and flexible tool for rendering shapes such as rectangles, circles, stars, and custom polygons. It can also be used to create complex shapes by combining multiple primitives, and it supports advanced features like gradients, textures, and masks.

import { Graphics } from 'pixi.js';

const graphics = new Graphics()
  .rect(50, 50, 100, 100)
  .fill(0xff0000);

可用形状

¥Available Shapes

PixiJS v8 支持多种形状基元：

¥PixiJS v8 supports a variety of shape primitives:

Basic Primitives

• Line
• Rectangle
• Rounded Rectangle
• Circle
• Ellipse
• Arc
• Bezier / Quadratic Curves

高级图元

¥Advanced Primitives

• 倒角矩形

  ¥Chamfer Rect

• 圆角矩形

  ¥Fillet Rect

• 正多边形

  ¥Regular Polygon

• 星星

  ¥Star

• 圆角多边形

  ¥Rounded Polygon

• 圆角形状

  ¥Rounded Shape

const graphics = new Graphics()
    .rect(50, 50, 100, 100)
    .fill(0xff0000)
    .circle(200, 200, 50)
    .stroke(0x00ff00)
    .lineStyle(5)
    .moveTo(300, 300)
    .lineTo(400, 400);

SVG 支持

¥SVG Support

你还可以加载 SVG 路径数据，但由于 Pixi 性能优化的三角测量系统，复杂的孔洞几何体渲染可能不准确。

¥You can also load SVG path data, although complex hole geometries may render inaccurately due to Pixi's performance-optimized triangulation system.

let shape = new Graphics().svg(`
  <svg>
    <path d="M 100 350 q 150 -300 300 0" stroke="blue" />
  </svg>
`);

GraphicsContext

GraphicsContext 类是 PixiJS 全新图形模型的核心。它包含所有绘图命令和样式，允许多个 Graphics 实例重复使用相同的形状数据：

¥The GraphicsContext class is the core of PixiJS's new graphics model. It holds all the drawing commands and styles, allowing the same shape data to be reused by multiple Graphics instances:

const context = new GraphicsContext().circle(100, 100, 50).fill('red');

const shapeA = new Graphics(context);
const shapeB = new Graphics(context); // Shares the same geometry

此模式在渲染重复或动画形状（例如基于帧的 SVG 交换）时特别有效：

¥This pattern is particularly effective when rendering repeated or animated shapes, such as frame-based SVG swaps:

let frames = [
    new GraphicsContext().circle(100, 100, 50).fill('red'),
    new GraphicsContext().rect(0, 0, 100, 100).fill('red'),
];

let graphic = new Graphics(frames[0]);

function update() {
    graphic.context = frames[1]; // Very cheap operation
}

信息

如果你在创建 Graphics 对象时没有显式传递 GraphicsContext，那么在内部，它将有自己的上下文，可通过 myGraphics.context 访问。

¥If you don't explicitly pass a GraphicsContext when creating a Graphics object, then internally, it will have its own context, accessible via myGraphics.context.

销毁 GraphicsContext

¥Destroying a GraphicsContext

销毁 GraphicsContext 时，所有共享它的 Graphics 实例也将被销毁。这一点至关重要，需要牢记，因为如果不小心，可能会导致意外行为。

¥When you destroy a GraphicsContext, all Graphics instances that share it will also be destroyed. This is a crucial point to remember, as it can lead to unexpected behavior if you're not careful.

const context = new GraphicsContext().circle(100, 100, 50).fill('red');
const shapeA = new Graphics(context);
const shapeB = new Graphics(context); // Shares the same geometry

shapeA.destroy({ context: true }); // Destroys both shapeA and shapeB

创建孔洞

¥Creating Holes

使用 .cut() 从前一个形状中移除一个形状：

¥Use .cut() to remove a shape from the previous one:

const g = new Graphics()
  .rect(0, 0, 100, 100)
  .fill(0x00ff00)
  .circle(50, 50, 20)
  .cut(); // Creates a hole in the green rectangle

确保孔洞完全包含在形状内，以避免三角测量错误。

¥Ensure the hole is fully enclosed within the shape to avoid triangulation errors.

图形的本质在于构建，而非绘制

¥Graphics Is About Building, Not Drawing

尽管 .rect() 或 .circle() 等函数的术语相同，但 Graphics 并不会立即绘制任何内容。相反，每个方法都会构建一个存储在 GraphicsContext 中的几何图元列表。这些叶节点随后会在对象绘制到屏幕上或在其他上下文（例如蒙版）中使用时进行渲染。

¥Despite the terminology of functions like .rect() or .circle(), Graphics does not immediately draw anything. Instead, each method builds up a list of geometry primitives stored inside a GraphicsContext. These are then rendered when the object is drawn to the screen or used in another context, such as a mask.

const graphic = new Graphics().rect(0, 0, 200, 100).fill(0xff0000);

app.stage.addChild(graphic); // The rendering happens here

你可以将 Graphics 视为蓝图构建器：它定义了要绘制的内容，但没有定义何时绘制。这就是为什么 Graphics 对象可以被重用、克隆、屏蔽和转换，而无需在实际渲染之前进行额外计算。

¥You can think of Graphics as a blueprint builder: it defines what to draw, but not when to draw it. This is why Graphics objects can be reused, cloned, masked, and transformed without incurring extra computation until they're actually rendered.

性能最佳实践

¥Performance Best Practices

• 无需每帧都清除并重建图形。如果你的内容是动态的，最好交换预先构建的 GraphicsContext 对象，而不是重新创建它们。

  ¥Do not clear and rebuild graphics every frame. If your content is dynamic, prefer swapping prebuilt GraphicsContext objects instead of recreating them.

• 完成后使用 Graphics.destroy() 进行清理。共享上下文不会自动销毁。

  ¥Use Graphics.destroy() to clean up when done. Shared contexts are not auto-destroyed.

• 使用多个简单的 Graphics 对象而不是一个复杂的对象来维护 GPU 批处理。

  ¥Use many simple Graphics objects over one complex one to maintain GPU batching.

• 除非你了解混合模式，否则请避免透明重叠；重叠的半透明图元将按图元进行交互，而不是在合成后进行交互。

  ¥Avoid transparent overlap unless you understand blend modes; overlapping semi-transparent primitives will interact per primitive, not post-composition.

注意事项和陷阱

¥Caveats and Gotchas

• 内存泄漏：不再需要时调用 .destroy()。

  ¥Memory Leaks: Call .destroy() when no longer needed.

• SVG 和孔洞：并非所有 SVG 空洞路径都能正确进行三角测量。

  ¥SVG and Holes: Not all SVG hole paths triangulate correctly.

• 改变几何形状：谨慎使用 .clear()。首选上下文切换。

  ¥Changing Geometry: Use .clear() sparingly. Prefer swapping contexts.

• 透明度和混合模式：这些适用于每个图元。如果要扁平化效果，请使用 RenderTexture。

  ¥Transparency and Blend Modes: These apply per primitive. Use RenderTexture if you want to flatten effects.

---

API 参考

¥API Reference

• 图形

  ¥Graphics

• GraphicsContext

• FillStyle

• StrokeStyle