Skip to content

Commit d1ca559

Browse files
tangying1027xuying.xu
tangying1027
and
xuying.xu
authored
feat: 增加magnifier组件 (#2075)
* feat: 增加magnifier组件 * feat: position&radius支持px * feat: 修改放大镜组件入参 --------- Co-authored-by: xuying.xu <xuying.xu@alibaba-inc.com>
1 parent 0a988e9 commit d1ca559

File tree

12 files changed

+934
-3
lines changed

12 files changed

+934
-3
lines changed

‎.cursor/rules/code-style.mdc‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# F2 Code Style Guidelines
2+
3+
This document outlines the coding standards and best practices for the F2 visualization library.
4+
5+
## TypeScript/JavaScript Style Guidelines
6+
7+
### General Formatting
8+
9+
- Use 2 spaces for indentation
10+
- Use single quotes for strings
11+
- Maximum line length: 100 characters
12+
- Use trailing commas in multi-line object literals and arrays
13+
- Use semicolons at the end of statements
14+
- Use LF line endings
15+
- Insert final newline at the end of files
16+
- Trim trailing whitespace
17+
18+
### Naming Conventions
19+
20+
- **Components**: Use PascalCase for component names (e.g., `LineChart`, `AreaSeries`)
21+
- **Functions**: Use camelCase for function names (e.g., `calculatePosition`, `formatData`)
22+
- **Variables**: Use camelCase for variable names (e.g., `dataSource`, `chartConfig`)
23+
- **Constants**: Use UPPER_SNAKE_CASE for constants (e.g., `DEFAULT_THEME`, `MAX_DATA_POINTS`)
24+
- **Interfaces/Types**: Use PascalCase with a descriptive name (e.g., `ChartProps`, `PointData`)
25+
- **Files**: Use kebab-case for file names (e.g., `line-chart.tsx`, `data-processor.ts`)
26+
27+
### Component Structure
28+
29+
- Each React component should be in its own file
30+
- Component props should be defined using TypeScript interfaces
31+
- Export components as named exports, not default exports
32+
- Keep components focused on a single responsibility
33+
- Use functional components with hooks instead of class components when possible
34+
35+
### Code Organization
36+
37+
- Group related functions and constants together
38+
- Place imports at the top of the file, grouped by:
39+
1. External libraries
40+
2. Internal modules
41+
3. Local imports (from the same directory)
42+
- Export public API from index files
43+
44+
### Documentation
45+
46+
- Use JSDoc comments for functions, classes, and interfaces
47+
- Document parameters, return values, and thrown exceptions
48+
- Include examples for complex functions or components
49+
- Keep comments up-to-date with code changes
50+
51+
### Best Practices
52+
53+
- Avoid using `any` type in TypeScript
54+
- Use optional chaining (`?.`) and nullish coalescing (`??`) operators
55+
- Prefer early returns to reduce nesting
56+
- Use destructuring for props and state
57+
- Avoid magic numbers, use named constants
58+
- Write unit tests for critical functionality
59+
- Use meaningful variable and function names
60+
- Avoid unnecessary comments that just repeat what the code does
61+
62+
## Visualization-Specific Guidelines
63+
64+
### Chart Components
65+
66+
- Follow a consistent API pattern across different chart types
67+
- Separate data processing logic from rendering logic
68+
- Implement proper accessibility features (ARIA attributes, keyboard navigation)
69+
- Support responsive layouts by default
70+
71+
### Performance
72+
73+
- Optimize rendering performance for large datasets
74+
- Use memoization for expensive calculations
75+
- Implement proper cleanup in component lifecycle methods
76+
- Avoid unnecessary re-renders
77+
78+
### Theming
79+
80+
- Use the theme system consistently
81+
- Don't hardcode colors or styles
82+
- Support dark mode where applicable
83+
84+
## Git Workflow
85+
86+
- Write clear, descriptive commit messages
87+
- Reference issue numbers in commit messages when applicable
88+
- Keep pull requests focused on a single feature or bug fix
89+
- Update documentation when changing public APIs
90+
91+
Following these guidelines will help maintain code quality and consistency throughout the F2 project.

‎.cursor/rules/documentation.mdc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# F2 Documentation Guidelines
2+
3+
This document outlines the standards for writing and maintaining documentation in the F2 visualization library.
4+
5+
## General Guidelines
6+
7+
- Write in clear, concise language
8+
- Use active voice when possible
9+
- Keep sentences and paragraphs short
10+
- Use proper spelling, grammar, and punctuation
11+
- Use consistent terminology throughout the documentation
12+
- Include code examples for complex concepts
13+
- Update documentation when changing related code
14+
15+
## Markdown Style
16+
17+
- Use ATX-style headers (`#` for h1, `##` for h2, etc.)
18+
- Use backticks for inline code references
19+
- Use fenced code blocks with language specifiers for multi-line code examples
20+
- Use bullet lists for unordered items
21+
- Use numbered lists for sequential steps
22+
- Use tables for structured data
23+
- Use proper link syntax `[text](url)` for hyperlinks
24+
- Use images sparingly and provide alt text
25+
26+
## API Documentation
27+
28+
- Document all public APIs
29+
- Include descriptions for parameters and return values
30+
- Specify parameter types and whether they are optional
31+
- Provide usage examples
32+
- Document default values
33+
- Mention any side effects or exceptions
34+
35+
## Example Structure
36+
37+
Each example should include:
38+
39+
1. A clear title describing what the example demonstrates
40+
2. A brief description of the purpose and use case
41+
3. Complete, runnable code
42+
4. Expected output or visualization
43+
5. Explanation of key concepts or techniques used
44+
45+
## Multilingual Documentation
46+
47+
- Maintain both English (`.en.md`) and Chinese (`.zh.md`) versions of documentation
48+
- Ensure consistent terminology between language versions
49+
- Update both language versions when making changes
50+
- Follow the translation guidelines in the translation.mdc file
51+
52+
## Directory Structure
53+
54+
- Place API documentation in `site/docs/api/`
55+
- Place tutorials in `site/docs/tutorial/`
56+
- Place examples in `site/examples/`
57+
- Use consistent file naming across directories
58+
59+
## Best Practices
60+
61+
- Keep documentation up-to-date with code changes
62+
- Review documentation regularly for accuracy
63+
- Test code examples to ensure they work as described
64+
- Seek feedback from users on documentation clarity
65+
- Use screenshots or diagrams to illustrate complex concepts
66+
- Link to related documentation when appropriate
67+
68+
Following these guidelines will help maintain high-quality, consistent documentation throughout the F2 project.

‎.cursor/rules/testing.mdc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# F2 Testing Guidelines
2+
3+
This document outlines the standards for writing and maintaining tests in the F2 visualization library.
4+
5+
## General Testing Principles
6+
7+
- Write tests for all new features and bug fixes
8+
- Follow the AAA pattern: Arrange, Act, Assert
9+
- Keep tests simple, focused, and fast
10+
- Tests should be independent of each other
11+
- Avoid test interdependencies
12+
- Test both expected and error cases
13+
- Use descriptive test names that explain what is being tested
14+
15+
## Test Structure
16+
17+
- Group related tests using `describe` blocks
18+
- Use nested `describe` blocks for logical grouping
19+
- Use `it` or `test` for individual test cases
20+
- Name tests descriptively using the pattern: "should [expected behavior] when [condition]"
21+
- Keep test files alongside the code they test with a `.test.tsx` or `.test.ts` extension
22+
23+
## Visual Testing
24+
25+
- Use snapshot testing for visual components
26+
- Include image snapshots for critical visual features
27+
- Update snapshots only when visual changes are intentional
28+
- Review snapshot diffs carefully before committing
29+
30+
## Test Coverage
31+
32+
- Aim for high test coverage, especially for core functionality
33+
- Focus on testing behavior, not implementation details
34+
- Test edge cases and boundary conditions
35+
- Test error handling and recovery
36+
37+
## Mocking
38+
39+
- Mock external dependencies
40+
- Use jest mock functions for callbacks and event handlers
41+
- Keep mocks as simple as possible
42+
- Reset mocks between tests
43+
44+
## Component Testing
45+
46+
- Test that components render without errors
47+
- Test component props and their effects
48+
- Test component interactions and state changes
49+
- Test accessibility features
50+
51+
## Performance Testing
52+
53+
- Write performance tests for critical paths
54+
- Establish performance baselines
55+
- Test with realistic data volumes
56+
- Monitor for performance regressions
57+
58+
## Best Practices
59+
60+
- Run tests before committing code
61+
- Fix failing tests immediately
62+
- Don't disable tests without a good reason and documentation
63+
- Keep test code clean and maintainable
64+
- Refactor tests when refactoring code
65+
- Use setup and teardown functions for common operations
66+
67+
Following these guidelines will help maintain a robust test suite for the F2 project, ensuring code quality and preventing regressions.

‎packages/f2/src/components/geometry/index.tsx‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,15 @@ const AdjustMap = {
2929
// 保留原始数据的字段
3030
const FIELD_ORIGIN = 'origin';
3131

32-
const OVERRIDE_FIELDS_SET = new Set(['color', 'normalized', 'x', 'y', 'shapeName', 'shape', 'selected']);
32+
const OVERRIDE_FIELDS_SET = new Set([
33+
'color',
34+
'normalized',
35+
'x',
36+
'y',
37+
'shapeName',
38+
'shape',
39+
'selected',
40+
]);
3341

3442
export type GeometryType = 'line' | 'point' | 'area' | 'polygon' | 'schema' | 'interval';
3543

@@ -557,7 +565,6 @@ class Geometry<
557565
const shapeName = attrValues.shape;
558566
const shape = this._getShapeStyle(shapeName, origin);
559567
const selected = this.isSelected(child);
560-
561568
// 饼图 Interval 的 y 值设置为 color, normalized, x, y, shapeName, shape, selected 等字段时,
562569
// 会导致取值异常
563570
mappedChildren.push({
@@ -670,7 +677,7 @@ class Geometry<
670677
return records.filter((record, idx) => {
671678
const isOverrideField = OVERRIDE_FIELDS_SET.has(yField);
672679
const rangeY = isOverrideField ? originRecordList[idx]?.[yField] : record[yField];
673-
if (rangeY?.[0] <= yValue && rangeY?.[1] >= yValue) {
680+
if (rangeY?.[0] <= yValue && rangeY?.[1] >= yValue) {
674681
return true;
675682
}
676683
return false;

‎packages/f2/src/components/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,4 @@ export {
3333
CandlestickView,
3434
} from './candlestick';
3535
export { default as Pictorial, PictorialProps } from './pictorial';
36+
export { default as Magnifier, MagnifierProps } from './magnifier';

‎packages/f2/src/components/magnifier/index.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import withMagnifier, { MagnifierProps } from './withMagnifier';
2+
import magnifierView from './magnifierView';
3+
4+
export type { MagnifierProps };
5+
export default withMagnifier(magnifierView);

‎packages/f2/src/components/magnifier/magnifierView.tsx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
import { jsx } from '@antv/f-engine';
2+
3+
export default (props) => {
4+
const { pointsData = [], radius, center, frameStyle, lineStyle, shape, linesData = [] } = props;
5+
const cx = center[0];
6+
const cy = center[1];
7+
8+
return (
9+
<group
10+
style={{
11+
clip: {
12+
type: 'circle',
13+
style: {
14+
cx,
15+
cy,
16+
r: radius,
17+
},
18+
},
19+
}}
20+
>
21+
{/* 放大镜外框 */}
22+
<circle
23+
style={{
24+
cx,
25+
cy,
26+
r: radius,
27+
fill: 'transparent',
28+
stroke: '#d8d8d8',
29+
lineWidth: '2px',
30+
...frameStyle,
31+
}}
32+
/>
33+
{/* 辅助线 */}
34+
{linesData.map((line) => (
35+
<line
36+
style={{
37+
x1: line.points[0].x,
38+
y1: line.points[0].y,
39+
x2: line.points[1].x,
40+
y2: line.points[1].y,
41+
stroke: '#d8d8d8',
42+
lineWidth: '5px',
43+
...line.style,
44+
}}
45+
/>
46+
))}
47+
{/* 折线 */}
48+
<polyline
49+
style={{
50+
points: pointsData.map((p) => [p.x, p.y]),
51+
stroke: pointsData[0].color,
52+
lineWidth: '5px',
53+
...shape,
54+
...lineStyle,
55+
}}
56+
animation={{
57+
appear: {
58+
easing: 'quadraticOut',
59+
duration: 450,
60+
clip: {
61+
type: 'rect',
62+
property: ['width'],
63+
style: {
64+
x: cx - radius,
65+
y: cy - radius,
66+
height: radius * 2,
67+
},
68+
start: {
69+
width: 0,
70+
},
71+
end: {
72+
width: radius * 2,
73+
},
74+
},
75+
},
76+
}}
77+
/>
78+
</group>
79+
);
80+
};

0 commit comments

Comments
 (0)