### Install project dependencies for local development

Source: https://github.com/antvis/f2/blob/master/README.md

Run this command to install all necessary dependencies for setting up the F2 project locally.

```bash
$ npm install
```

--------------------------------

### Local Development Commands for F2

Source: https://github.com/antvis/f2/blob/master/packages/f2/README.md

These commands are used for setting up and running the F2 project locally, including installing dependencies, running tests, and starting the development server.

```bash
$ npm install

# 先初始化 monorepo
$ npm run bootstrap

# 再跑测试用例
$ npm run test

# 监听文件变化构建，并打开 demo 页面
$ npm run dev

# 打开某一个具体的测试用例
$ npm run test-watch -- 'TestFileName'
```

--------------------------------

### Dynamic PointGuide Styling with Function (Full Example)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/point-guide.zh.md

Illustrates a full chart setup where the `PointGuide`'s style is dynamically determined by a function, adjusting fill color and radius based on normalized y-position.

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    {data.map((item) => (
      <PointGuide
        records={[item]}
        style={(points, chart) => {
          const y = points[0].y;
          const { top, bottom } = chart.layout;
          const normalizedY = (y - bottom) / (top - bottom);
          return {
            fill: normalizedY > 0.7 ? 'red' : 'gray',
            r: normalizedY > 0.7 ? 6 : 4,
          };
        }}
      />
    ))}
  </Chart>
</Canvas>
```

--------------------------------

### Install F2 and mini program dependencies

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/framework/miniprogram.zh.md

Install F2 core library and platform-specific adapters for Alipay or WeChat mini programs.

```bash
# 安装 F2 依赖
npm i @antv/f2 --save

# 支付宝小程序
npm i @antv/f-my --save

# 微信小程序
npm i @antv/f-wx --save
```

--------------------------------

### 解决从指定帧开始不生效问题

Source: https://github.com/antvis/f2/blob/master/site/docs/api/timeline.zh.md

解释了 `start` 属性值超出有效范围时，从指定帧开始播放会不生效，并提供了正确和错误的示例。

```jsx
// 如果有 5 个子组件，start 的有效范围是 0-4
<Timeline delay={1000} start={2}>  {/* 正确 */}
```

```jsx
<Timeline delay={1000} start={10}> {/* 错误：超出范围 */}
```

--------------------------------

### Initialize monorepo for F2 local development

Source: https://github.com/antvis/f2/blob/master/README.md

After installing dependencies, run this command to initialize the monorepo structure for the F2 project.

```bash
$ npm run bootstrap
```

--------------------------------

### ImageGuide Dynamic Style Function Example (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

An example of using a function for the `style` prop to conditionally set image dimensions based on the y-coordinate of the data point.

```jsx
<ImageGuide
  records={[{ genre: 'Sports', sold: 275 }]}
  src="https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png"
  style={(points) => ({
    width: points[0].y > 0.5 ? 32 : 24,
    height: points[0].y > 0.5 ? 32 : 24,
  })}
/>
```

--------------------------------

### Install F2 via npm

Source: https://github.com/antvis/f2/blob/master/packages/f2/README.md

Use npm to install the F2 visualization library as a project dependency.

```bash
$ npm install @antv/f2
```

--------------------------------

### ImageGuide Basic Usage with Multiple Annotations (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

Provides an example of iterating through a dataset to render multiple `ImageGuide` annotations on a chart.

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    {data.map((item) => (
      <ImageGuide
        records={[item]}
        src="https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png"
        style={{ width: 24, height: 24 }}
      />
    ))}
  </Chart>
</Canvas>
```

--------------------------------

### Configuring Point Size Property

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/point.zh.md

Examples demonstrating different methods to specify the size of points, such as fixed values, field mapping, array format, and object configurations.

```jsx
<Point size={4} />
```

```jsx
<Point size="value" />
```

```jsx
<Point size={["val", [2, 4, 6]]} />
```

```jsx
<Point size={{ field: "val", range: [2, 10] }} />
```

```jsx
<Point size={{ type: "linear", field: "val" }} />
```

--------------------------------

### Basic PointGuide Usage with JSX

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/point-guide.zh.md

Demonstrates how to integrate `PointGuide` into an F2 chart to annotate data points. It iterates through data to place a guide at each point.

```jsx
import { Canvas, Chart, Line, PointGuide } from '@antv/f2';

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    {data.map((item) => (
      <PointGuide
        records={[item]}
        offsetX={0}
        offsetY={0}
        style={{ fill: '#f00' }}
      />
    ))}
  </Chart>
</Canvas>
```

--------------------------------

### Install F2 and Canvas dependencies

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/framework/nodejs.zh.md

Install the required npm packages for using F2 in Node.js with Canvas support.

```bash
npm install @antv/f2 --save
npm install canvas --save
```

--------------------------------

### PointGuide Component Usage

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/point-guide.zh.md

Basic example of using the PointGuide component to add point annotations to a line chart.

```APIDOC
## PointGuide Component

### Description

The `PointGuide` component is used to add point annotations to charts. It allows you to mark specific data points or positions with customizable visual styles.

### Props

- `records` (Array<RecordItem>) - Required - Specifies the data items or proportional values for the annotation position. Supports special values like 'min', 'max', 'median', and percentages.
- `offsetX` (number | string) - Optional - Offset on the x-axis. Defaults to `0`.
- `offsetY` (number | string) - Optional - Offset on the y-axis. Defaults to `0`.
- `style` (Partial<CircleStyleProps> | Function) - Optional - Defines the style of the point annotation. Can be a static style object or a function that dynamically calculates style based on points and chart instance. Defaults to `{ fill: '#fff', r: 3, lineWidth: 2, stroke: '#1890ff' }`.
- `animation` (AnimationProps | Function) - Optional - Configuration for animations. Refer to the animation documentation for details.
- `onClick` ((ev: Event) => void) - Optional - Callback function for click events on the annotation.
- `visible` (boolean) - Optional - Controls the visibility of the annotation. Defaults to `true`.
- `precise` (boolean) - Optional - Enables precise positioning, especially useful for grouped bar charts.

### Records Special Values

- `'min'`: Minimum value (0)
- `'max'`: Maximum value (1)
- `'median'`: Median value (0.5)
- `'0%'`: 0% position (0.0)
- `'50%'`: 50% position (0.5)
- `'100%'`: 100% position (1.0)

### Style Property

The `style` property can be an object for static styling or a function for dynamic styling based on `points` and `chart`.

### Example Usage

```jsx
import { Canvas, Chart, Line, PointGuide } from '@antv/f2';

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    {data.map((item) => (
      <PointGuide
        records={[item]}
        offsetX={0}
        offsetY={0}
        style={{ fill: '#f00' }}
      />
    ))}
  </Chart>
</Canvas>
```
```

--------------------------------

### 从指定位置开始播放时间轴

Source: https://github.com/antvis/f2/blob/master/site/docs/api/timeline.zh.md

演示了如何使用 `start` 属性让 Timeline 组件从指定的子组件索引位置开始播放动画。

```jsx
<Canvas context={context}>
  <Timeline delay={800} start={2}>
    {dataFrames.map((frame, index) => (
      <Chart key={index} data={frame}>
        <Interval x="x" y="y" />
      </Chart>
    ))}
  </Timeline>
</Canvas>
```

--------------------------------

### Render a Basic Bar Chart with F2

Source: https://github.com/antvis/f2/blob/master/packages/f2/README.md

This example demonstrates how to initialize an F2 chart with sample data, configure axes, and render an interval (bar) chart on a canvas element using JSX syntax.

```jsx
// F2 对数据源格式的要求，仅仅是 JSON 数组，数组的每个元素是一个标准 JSON 对象。
const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 }
];

// 获取 canvas context
const context = document.getElementById('mountNode').getContext('2d');
const { props } = (
  <Canvas context={context} pixelRatio={window.devicePixelRatio}>
    <Chart data={data}>
      <Axis field="genre" />
      <Axis field="sold" />
      <Interval x="genre" y="sold" color="genre" />
      <Tooltip />
    </Chart>
  </Canvas>
);

const canvas = new Canvas(props);
await canvas.render();
```

--------------------------------

### Create and render F2 chart in Node.js

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/framework/nodejs.zh.md

Complete example showing how to create a Canvas instance, render an F2 chart with sample data, and export it as a PNG file. Animations are disabled for image export scenarios.

```jsx
import { Canvas, Chart, Interval, Axis } from '@antv/f2';
import { createCanvas } from 'canvas';
import fs from 'fs';
import path from 'path';

const canvas = createCanvas(200, 200);
const ctx = canvas.getContext('2d');

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

(async () => {
  const { props } = (
    <Canvas context={ctx} pixelRatio={1} animate={false}>
      <Chart data={data}>
        <Axis field="genre" />
        <Axis field="sold" />
        <Interval x="genre" y="sold" color="genre" />
      </Chart>
    </Canvas>
  );

  const fcanvas = new Canvas(props);
  await fcanvas.render();

  const out = fs.createWriteStream(path.join(__dirname, 'chart.png'));
  const stream = canvas.createPNGStream();
  stream.pipe(out);

  out.on('finish', () => {
    process.exit();
  });
})();
```

--------------------------------

### TextGuide Dynamic Styling with Function (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/text-guide.zh.md

Provides a full example of using a function for the `style` prop to dynamically change text color and font size based on the `item.sold` value, making annotations visually distinct.

```jsx
<TextGuide
  records={[item]}
  content={item.sold}
  style={(points, chart) => ({
    fill: item.sold > 200 ? 'red' : 'black',
    fontSize: item.sold > 200 ? '28px' : '20px',
    textAlign: 'center',
  })}
/>
```

--------------------------------

### PointGuide Dynamic Style Function

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/point-guide.zh.md

Demonstrates using a function for the `style` prop to dynamically determine the guide's appearance based on its position or chart data.

```jsx
style={(points, chart) => ({
  fill: points[0].y > 0.5 ? '#f00' : '#00f'
})}
```

--------------------------------

### RectGuide Component Properties and Usage

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/rect-guide.zh.md

Detailed documentation for the RectGuide component, including its properties, special value handling for records, style customization, and various usage examples.

```APIDOC
## Component: RectGuide

### Description
The `RectGuide` component is used to draw rectangular annotation areas on an F2 chart. It requires two points to define the rectangle, which can be specified using data records or special string values.

### Props
- **records** (Array<RecordItem>) - Required - 矩形两个顶点对应的位置，**需要 2 个点来定义矩形**，支持特殊值。
- **offsetX** (number | string) - Optional - Default: `0` - x 轴偏移量，支持数字或带单位的字符串（如 '10px'）。
- **offsetY** (number | string) - Optional - Default: `0` - y 轴偏移量，支持数字或带单位的字符串（如 '10px'）。
- **style** (RectStyleProps | Function) - Optional - 矩形样式，支持对象或函数形式。
- **animation** (AnimationProps | Function) - Optional - 动画配置，详见 [动画文档](/tutorial/animation)。
- **onClick** ((ev) => void) - Optional - 点击事件回调。
- **visible** (boolean) - Optional - Default: `true` - 是否显示。
- **precise** (boolean) - Optional - 是否精确定位（用于 dodge 调整时的位置计算）。

### Special `records` Values
The `records` prop can accept special string values to represent positions without needing specific numerical calculations:

| Value | Meaning | Corresponding Position |
|-------|---------|------------------------|
| `'min'` | 最小值 | 0 |
| `'max'` | 最大值 | 1 |
| `'median'` | 中位值 | 0.5 |
| `'50%'` | 50% 位置 | 0.5 |
| `'100%'` | 100% 位置 | 1.0 |

### `style` Property Details
The `style` prop supports two forms:

#### Object Form (Static Style)
Used for applying static styles to the rectangle.
```jsx
style={{ fill: 'yellow', fillOpacity: 0.5, stroke: 'red', lineWidth: 2 }}
```

#### Function Form (Dynamic Style)
Used for applying dynamic styles based on the rectangle's position or chart data. The function signature is `(points: Point[], chart: Chart) => RectStyleProps`.
- `points`: An array of two canvas pixel coordinates for the rectangle's vertices, each containing `x` and `y` properties.
- `chart`: The chart instance, providing access to chart configurations and layout information.
```jsx
style={(points, chart) => {
  const height = Math.abs(points[1].y - points[0].y);
  return {
    fill: height > 100 ? 'red' : 'green',
    fillOpacity: 0.3,
    stroke: height > 100 ? 'darkred' : 'darkgreen',
  };
}}
```

### Usage Examples

#### Basic Usage: Marking an Area Between Two Data Points
```jsx
<RectGuide
  records={[data[0], data[1]]}
  style={{ fill: 'yellow', fillOpacity: 0.5 }}
  offsetX="-24px"
  offsetY="24px"
/>
```

#### Marking Min to Max Area Using Special Values
```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: 'max' }
  ]}
  style={{ fill: 'rgba(255, 0, 0, 0.2)' }}
/>
```

#### Dynamic Style with Function Example
```jsx
<RectGuide
  records={[data[0], data[1]]}
  style={(points, chart) => {
    // points 是画布像素坐标
    const height = Math.abs(points[1].y - points[0].y);
    return {
      fill: height > 100 ? 'red' : 'green',
      fillOpacity: 0.3,
      stroke: height > 100 ? 'darkred' : 'darkgreen',
    };
  }}
/>
```

#### Semi-Transparent Fill Area
```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: 'max' }
  ]}
  style={{
    fill: 'blue',
    fillOpacity: 0.1,
    stroke: 'blue',
    lineWidth: 1,
    lineDash: [4, 4]
  }}
/>
```

#### Multiple Rectangular Areas Combination
```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: '50%' },
    { genre: 'Sports', sold: 'max' }
  ]}
  style={{ fill: 'red', fillOpacity: 0.1 }}
/>
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: '50%' }
  ]}
  style={{ fill: 'green', fillOpacity: 0.1 }}
/>
```

#### Using Animation
```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: 'max' }
  ]}
  style={{ fill: 'yellow', fillOpacity: 0.5 }}
  animation={{
    appear: {
      duration: 450,
      easing: 'linear'
    }
  }}
/>
```
```

--------------------------------

### Configuring Point Color Property

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/point.zh.md

Examples showing various ways to set the color of points, including fixed values, field mapping, array format, and object configurations.

```jsx
<Point color="#1890FF" />
```

```jsx
<Point color="category" />
```

```jsx
<Point color={["cat", ["red", "blue"]]} />
```

```jsx
<Point color={{ field: "cat", range: ["red", "blue"] }} />
```

```jsx
<Point color={{ type: "linear", field: "val" }} />
```

--------------------------------

### Apply Animation to Line Guide in F2

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

This snippet demonstrates how to apply an 'appear' animation to a LineGuide, making the line grow from bottom to top.

```jsx
<LineGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: 275 }
  ]}
  style={{ stroke: '#f00', lineWidth: 2 }}
  animation={(points, chart) => ({
    appear: {
      duration: 800,
      easing: 'easeOut',
      property: ['y2'],  // 支持端点坐标动画：x1, y1, x2, y2
      start: { y2: points[0].y },  // 从起点开始
      end: { y2: points[1].y }     // 生长到终点
    }
  })}
/>
```

--------------------------------

### onPressStart

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/event.zh.md

The `onPressStart` event property is triggered when a user's finger begins a sustained press on a graphic element. This can indicate the start of a long-press interaction.

```APIDOC
## Event Property: onPressStart

### Description
Triggered when a finger starts pressing on the graphic.

### Type
function
```

--------------------------------

### Use Children.toArray to convert child elements

Source: https://github.com/antvis/f2/blob/master/site/docs/api/f2.zh.md

Example of using Children.toArray to convert child elements to array form for array operations like getting the count of children.

```jsx
import { Children } from '@antv/f2';

function analyzeChildren(children) {
  // 将子元素转换为数组以便进行数组操作
  const childrenArray = Children.toArray(children)
  const count = childrenArray.length

  return <text>共有 {count} 个子元素</text>
}
```

--------------------------------

### 为 ImageGuide 图片标注添加动画效果 (React/JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

通过配置 `animation` 属性，为 ImageGuide 组件设置出现动画，例如透明度渐变效果。

```jsx
<ImageGuide
  records={[{ genre: 'Sports', sold: 275 }]}
  src="https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png"
  style={{ width: 24, height: 24 }}
  animation={{
    appear: {
      property: ['opacity'],
      duration: 1000,
      easing: 'easeOut',
      start: {
        opacity: 0,
      },
      end: {
        opacity: 1,
      },
    }
  }}
/>
```

--------------------------------

### Basic Tooltip Usage with Line Chart

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/tooltip.zh.md

Import Tooltip component and add it to a Chart to enable interactive data display on hover or press. The example shows a basic setup with a line chart displaying genre and sales data.

```jsx
import { Canvas, Chart, Line, Tooltip } from '@antv/f2';

const data = [
  { genre: 'Sports', sold: 5 },
  { genre: 'Strategy', sold: 10 },
  { genre: 'Action', sold: 20 },
  { genre: 'Shooter', sold: 20 },
  { genre: 'Other', sold: 40 },
];

<Canvas context={context}>
  <Chart data={data}>
    <Tooltip />
    <Axis field="genre" />
    <Line x="genre" y="sold" />
  </Chart>
</Canvas>;
```

--------------------------------

### 处理 ImageGuide 的点击事件 (React/JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

使用 `onClick` 属性为 ImageGuide 组件添加点击事件监听器，以获取点击位置信息。

```jsx
<ImageGuide
  records={[{ genre: 'Sports', sold: 275 }]}
  src="https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png"
  style={{ width: 24, height: 24 }}
  onClick={(ev) => {
    console.log('点击位置:', ev.points);
  }}
/>
```

--------------------------------

### Install Babel JSX Transform Plugin

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/framework/jsx-transform.zh.md

Install the necessary Babel plugin for JSX transformation as a development dependency.

```bash
npm install --save-dev @babel/plugin-transform-react-jsx
```

--------------------------------

### Linear Gradient Function Example (CSS)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of a linear gradient function string, specifying an angle and color stops.

```css
`linear-gradient(90deg, red, blue)`
```

--------------------------------

### Build F2 project and open demo page with file watch

Source: https://github.com/antvis/f2/blob/master/README.md

This command watches for file changes, rebuilds the project, and opens the demo page for development.

```bash
$ npm run dev
```

--------------------------------

### ImageGuide Static Style Object (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

Demonstrates how to apply static width and height styles to the `ImageGuide` component using a plain object for the `style` prop.

```jsx
style={{ width: 24, height: 24 }}
```

--------------------------------

### Radial Gradient Function Example (CSS)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of a radial gradient function string, specifying shape, position, and color stops.

```css
`radial-gradient(circle at center, red, blue)`
```

--------------------------------

### Configure Alipay mini program compilation script

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/framework/miniprogram.zh.md

Set up the beforeCompile hook in mini.project.json to run the JSX transformation.

```json
{
  "scripts": {
    "beforeCompile": "npm run beforeCompile"
  }
}
```

--------------------------------

### Example Commit Message with Breaking Change

Source: https://github.com/antvis/f2/blob/master/CONTRIBUTING.zh-CN.md

This example demonstrates a detailed commit message, including type, scope, subject, body, and footer, specifically highlighting a breaking change and linking to related issues.

```text
fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Document change on antvis/f2#12

Closes #392

BREAKING CHANGE:

  Breaks foo.bar api, foo.baz should be used instead
```

--------------------------------

### RectGuide 动态样式计算

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/rect-guide.zh.md

将 style 属性设置为一个函数，该函数接收 points 和 chart 实例作为参数，允许根据图表布局信息动态计算并返回样式对象。

```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Action', sold: 'max' },
  ]}
  style={(points, chart) => {
    // points 已是画布像素坐标
    const rectWidth = Math.abs(points[1].x - points[0].x);
    return {
      fill: rectWidth > 200 ? 'blue' : 'orange',
      fillOpacity: 0.3
    };
  }}
/>
```

--------------------------------

### Apply Circular Clipping to a Rectangle (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of clipping a rectangle with a circular path, defining the visible area of the shape.

```jsx
// 圆形裁剪
<rect
  style={{
    x: 100,
    y: 100,
    width: 100,
    height: 100,
    fill: 'blue',
    clip: {
      type: 'circle',
      style: {
        cx: 150,
        cy: 150,
        r: 50,
      },
    },
  }}
/>
```

--------------------------------

### Apply Radial Gradient Stroke to a Circle (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of using a radial gradient string directly as the `stroke` value for a circle.

```jsx
// 径向渐变描边
<circle
  style={{
    cx: 100,
    cy: 100,
    r: 50,
    stroke: 'radial-gradient(circle, white, black)',
    lineWidth: 5,
  }}
/>
```

--------------------------------

### PointGuide Static Style Object

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/point-guide.zh.md

Shows how to apply a static style to `PointGuide` using a plain object for the `style` prop.

```jsx
style={{ fill: '#f00', stroke: '#000', lineWidth: 2 }}
```

--------------------------------

### Apply Linear Gradient Fill to a Rectangle (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of using a linear gradient string directly as the `fill` value for a rectangle.

```jsx
// 线性渐变填充
<rect
  style={{
    x: 10,
    y: 10,
    width: 200,
    height: 100,
    fill: 'linear-gradient(90deg, red 0%, yellow 50%, blue 100%)',
  }}
/>
```

--------------------------------

### Apply Rectangular Clipping to a Rectangle (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/shape-attrs.zh.md

Example of clipping a rectangle with another rectangular path, defining the visible area of the shape.

```jsx
// 矩形裁剪
<rect
  style={{
    x: 100,
    y: 100,
    width: 200,
    height: 200,
    fill: 'red',
    clip: {
      type: 'rect',
      style: {
        x: 150,
        y: 150,
        width: 100,
        height: 100,
      },
    },
  }}
/>
```

--------------------------------

### TextGuide Static Style Object (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/text-guide.zh.md

Shows how to apply static styling to the TextGuide component using a plain object for the `style` prop, setting properties like fill color, font size, and text alignment.

```jsx
style={{ fill: '#000', fontSize: '24px', textAlign: 'center' }}
```

--------------------------------

### Basic TextGuide Usage in F2 Chart (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/text-guide.zh.md

Demonstrates how to import and use the TextGuide component within a F2 Chart to annotate data points with their 'sold' values, applying basic styling for fill, font size, text alignment, and baseline.

```jsx
import { Canvas, Chart, Interval, TextGuide } from '@antv/f2';

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

<Canvas context={context}>
  <Chart data={data}>
    <Interval x="genre" y="sold" />
    {data.map((item) => (
      <TextGuide
        records={[item]}
        content={`${item.sold}`}
        style={{ fill: '#000', fontSize: '24px', textAlign: 'center', textBaseline: 'bottom' }}
      />
    ))}
  </Chart>
</Canvas>
```

--------------------------------

### RectGuide 标记两个数据点之间的区域

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/rect-guide.zh.md

一个完整的图表示例，使用 RectGuide 标记两个具体数据点之间的区域，并应用 `offsetX` 和 `offsetY` 进行位置调整。

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    <RectGuide
      records={[data[0], data[1]]}
      style={{ fill: 'yellow', fillOpacity: 0.5 }}
      offsetX="-24px"
      offsetY="24px"
    />
  </Chart>
</Canvas>
```

--------------------------------

### Custom Legend Container Style

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/legend.zh.md

Applies custom flexbox styles to the legend container, aligning items to the start and arranging them in a column.

```jsx
<Legend
  style={{
    justifyContent: 'flex-start',
    flexDirection: 'column',
  }}
/>
```

--------------------------------

### Get origin legend items

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/legend.zh.md

Retrieve the original category data from the legend component using getOriginItems() method on the legend instance.

```javascript
const legend = chartRef.current.getComponents().find(c => c.type === 'legend')
const items = legend.getOriginItems()
```

--------------------------------

### LineGuide TypeScript 类型定义

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

定义了 LineGuide 组件的属性接口，包括 records、offsetX、offsetY、style 和 animation。

```typescript
interface LineGuideProps {
  /** 标注位置的数据项或比例值（需要 2 个点来定义线） */
  records: RecordItem[];
  /** x 轴偏移量，支持数字、字符串或数组（为数组时可为两个端点分别设置不同偏移） */
  offsetX?: number | string | (number | string)[];
  /** y 轴偏移量，支持数字、字符串或数组（为数组时可为两个端点分别设置不同偏移） */
  offsetY?: number | string | (number | string)[];
  /** 线样式，支持对象或函数形式（函数接收 points 和 chart 参数）*/
  style?: Partial<LineStyleProps> | ((points: Point[], chart: Chart) => Partial<LineStyleProps>);
  /** 动画配置，详见 [动画文档](/tutorial/animation) */
  animation?: AnimationProps | ((points: Point[], chart: Chart) => AnimationProps);
}
```

--------------------------------

### Basic Magnifier with Focus Range

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/magnifier.zh.md

Simple example showing how to specify a focus range [3, 6] to display the magnifier on a line chart.

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="date" y="value" />
    <Magnifier focusRange={[3, 6]} />
  </Chart>
</Canvas>
```

--------------------------------

### RectGuide 点击事件处理

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/rect-guide.zh.md

使用 onClick 属性为 RectGuide 组件添加点击事件监听器，当用户点击矩形引导区域时触发回调函数。

```jsx
<RectGuide
  records={[
    { genre: 'Sports', sold: 'min' },
    { genre: 'Sports', sold: 'max' },
  ]}
  style={{ fill: 'yellow', fillOpacity: 0.5 }}
  onClick={(ev) => {
    console.log('RectGuide clicked:', ev);
  }}
/>
```

--------------------------------

### Fix Magnifier position (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/magnifier.zh.md

This example demonstrates how to fix the Magnifier component at a specific position on the chart using the `position` property and setting a `radius`.

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="date" y="value" />
    <Magnifier
      focusRange={[0, 4]}
      radius="50px"
      position={[200, 150]}
    />
  </Chart>
</Canvas>
```

--------------------------------

### RectGuide style 函数形式在图表中的应用

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/rect-guide.zh.md

在完整的图表上下文中，展示如何使用 `style` 属性的函数形式，根据矩形的高度动态设置填充颜色和边框样式。

```jsx
<RectGuide
  records={[data[0], data[1]]}
  style={(points, chart) => {
    // points 是画布像素坐标
    const height = Math.abs(points[1].y - points[0].y);
    return {
      fill: height > 100 ? 'red' : 'green',
      fillOpacity: 0.3,
      stroke: height > 100 ? 'darkred' : 'darkgreen',
    };
  }}
/>
```

--------------------------------

### LineGuide style 属性对象形式

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

展示 LineGuide 的 `style` 属性如何接受一个对象，用于设置静态的线样式，例如颜色、线宽和虚线模式。

```jsx
style={{ stroke: '#f00', lineWidth: 2, lineDash: [4, 4] }}
```

--------------------------------

### ImageGuide Dynamic Style Function (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

Shows how to use a function for the `style` prop to dynamically adjust image dimensions based on chart data points.

```jsx
style={(points, chart) => ({
  width: points[0].y > 0.5 ? 30 : 20,
  height: points[0].y > 0.5 ? 30 : 20,
})}
```

--------------------------------

### Axis Line End Markers

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/axis.zh.md

Add custom arrow or other symbol markers to the start and/or end of the axis line using the `style.symbol` property.

```APIDOC
## Component: <Axis>

### Property: `style.symbol` (array)

### Description
Configure custom symbols, such as arrows, to appear at the ends of the axis line. The `style.symbol` property accepts an array to define markers for both the maximum and minimum value ends of the axis.

### Parameters/Options
- **field** (string) - Required - The data field associated with the axis.
- **style.line** (object) - Optional - An object for styling the axis line itself.
- **style.symbol** (array<object>) - Optional - An array defining symbols for the axis ends.
    - **Array Structure**: `[max_value_end_symbol_object, min_value_end_symbol_object]`
    - **Symbol Object Properties**:
        - `type` (string) - The type of symbol, e.g., `'arrow'`, `'circle'`.

### Usage Example
```jsx
<Axis
  field="value"
  style={{
    line: {},
    symbol: [{ type: 'arrow' }], // Example: single arrow at the max value end
  }}
/>
```
```

--------------------------------

### LineGuide style 属性函数形式

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

展示 LineGuide 的 `style` 属性如何接受一个函数，用于根据点的坐标和图表实例动态设置线的样式。

```jsx
style={(points, chart) => ({
  stroke: '#f00',
  lineWidth: 2,
  lineDash: [4, 4],
})}
```

--------------------------------

### LineGuide style 属性动态颜色

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

展示 LineGuide 的 `style` 属性如何接受一个函数，根据线的方向（上升或下降）动态设置其颜色。

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    <LineGuide
      records={[
        { genre: 'Sports', sold: 'min' },
        { genre: 'Sports', sold: 'max' },
      ]}
      style={(points, chart) => {
        // Canvas 坐标系中 y 轴向下，points[0].y > points[1].y 表示上升
        const isRising = points[0].y > points[1].y;
        return {
          stroke: isRising ? 'green' : 'red',
          lineWidth: 2,
        };
      }}
    />
  </Chart>
</Canvas>
```

--------------------------------

### Set Magnifier position (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/magnifier.zh.md

This example shows how to explicitly set the Magnifier's center position using the `position` property. The `focusRange` is also required.

```jsx
// 如果希望放大镜在指定位置
<Magnifier
  focusRange={[2, 5]}
  position={[400, 100]}
/>
```

--------------------------------

### 配置 F2 图形入场动画 (Appear Animation) - React JSX

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/animation.zh.md

此代码展示如何为 F2 图形配置 `appear` 阶段的入场动画，通过定义 `property`、`start` 和 `end` 状态，使图形从一个位置平滑移动到另一个位置。

```jsx
<text
  style={{
    text: '测试',
    x: 100,
    y: 100,
  }}
  animation={{
    appear: {
      easing: 'linear',
      duration: 450,
      property: ['x', 'y'],
      start: {
        x: 0,
        y: 0,
      },
      end: {
        x: 100,
        y: 100,
      },
    },
  }}
/>
```

--------------------------------

### 组合多个 ImageGuide 图片标注 (React/JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

展示如何在 F2 图表中使用多个 ImageGuide 组件，以在不同数据点上显示不同的图片图标。

```jsx
// 绿色小圆点
const dotIcon = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIHZpZXdCb3g9IjAgMCAxMiAxMiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI2IiBjeT0iNiIgcj0iNSIgZmlsbD0iIzUyYzQxYSIvPjwvc3ZnPg==';
// 黄色星形图标
const starIcon = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cG9seWdvbiBwb2ludHM9IjE2LDIgMjAsMTIgMzAsMTIgMjIsMTggMjUsMjggMTYsMjIgNywyOCAxMCwxOCAyLDEyIDEyLDEyIiBmaWxsPSIjZmFhZDE0Ii8+PC9zdmc+';

<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" color="type" />
    {/* 在数据点上显示小圆点 */}
    {data.map((item) => (
      <ImageGuide
        records={[item]}
        src={dotIcon}
        style={{ width: 12, height: 12 }}
      />
    ))}
    {/* 在每个类别的最大值位置显示星形图标 */}
    {data.map((item) => (
      <ImageGuide
        records={[{ genre: item.genre, sold: 'max' }]}
        src={starIcon}
        style={{ width: 32, height: 32 }}
        offsetY="-10px"
      />
    ))}
  </Chart>
</Canvas>
```

--------------------------------

### onTouchStart

Source: https://github.com/antvis/f2/blob/master/site/docs/tutorial/event.zh.md

The `onTouchStart` event property is triggered when a user's finger first makes contact with a graphic element. This is a low-level touch event, useful for general touch detection.

```APIDOC
## Event Property: onTouchStart

### Description
Triggered when a finger touches the graphic.

### Type
function
```

--------------------------------

### Basic Magnifier Setup with Line Chart

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/magnifier.zh.md

Import Magnifier component and apply it to a line chart with a specified focus range to display magnified data points.

```jsx
import { Canvas, Chart, Line, Magnifier } from '@antv/f2';

const data = [
  { date: '2024-01-01', value: 10 },
  { date: '2024-01-02', value: 15 },
  { date: '2024-01-03', value: 8 },
  { date: '2024-01-04', value: 25 },
  { date: '2024-01-05', value: 30 },
  { date: '2024-01-06', value: 28 },
  { date: '2024-01-07', value: 35 },
];

<Canvas context={context} pixelRatio={window.devicePixelRatio}>
  <Chart data={data}>
    <Line x="date" y="value" />
    <Magnifier focusRange={[2, 5]} />
  </Chart>
</Canvas>
```

--------------------------------

### ImageGuide Basic Usage in F2 (JSX)

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/image-guide.zh.md

Illustrates how to import and use the `ImageGuide` component to add a single image annotation to a chart at a specific data point.

```jsx
import { Canvas, Chart, Line, ImageGuide } from '@antv/f2';

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 }
];

// 黄色星形图标
const starIcon = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cG9seWdvbiBwb2ludHM9IjEyLDIgMTUsOSAyMiw5IDE3LDE0IDE5LDIxIDEyLDE3IDUsMjEgNywxNCAyLDkgOSw5IiBmaWxsPSIjZmFhZDE0Ii8+Cjwvc3ZnPg==';

<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    <ImageGuide
      records={[data[3]]}
      src={starIcon}
      style={{ width: 36, height: 36 }}
    />
  </Chart>
</Canvas>
```

--------------------------------

### Use Children.map to iterate over child elements

Source: https://github.com/antvis/f2/blob/master/site/docs/api/f2.zh.md

Example of using Children.map to iterate and process child elements within a parent component. Each child is processed through the callback function.

```jsx
import { Children } from '@antv/f2';

function ParentComponent({ children }) {
  return (
    <group>
      {Children.map(children, (child) => {
        // 对每个子元素进行处理
        return child
      })}
    </group>
  )
}
```

--------------------------------

### LineGuide 虚线样式

Source: https://github.com/antvis/f2/blob/master/site/docs/api/chart/guide/line-guide.zh.md

展示如何通过 `style` 属性设置 `lineDash` 来创建虚线样式的 LineGuide，用于视觉区分。

```jsx
<Canvas context={context}>
  <Chart data={data}>
    <Line x="genre" y="sold" />
    <LineGuide
      records={[
        { genre: 'Sports', sold: 'min' },
        { genre: 'Sports', sold: 'max' },
      ]}
      style={{ stroke: '#999', lineWidth: 1, lineDash: [4, 4] }}
    />
  </Chart>
</Canvas>
```

--------------------------------

### 标记标注

Source: https://github.com/antvis/f2/blob/master/site/examples/component/guide/index.zh.md

使用 TagGuide 组件添加标签标注。

```jsx
import { TagGuide } from '@antv/f2';

<TagGuide
  records={[{ genre: 'Sports', sold: 5 }]}
  content="标签内容"
  direct="tr"
  background={{ fill: '#fff' }}
  textStyle={{ fill: '#000' }}
/>;
```