|
| 1 | +# API Tiering Guide |
| 2 | + |
| 3 | +This document groups `react-virtualized-diff` APIs into usage tiers so teams can pick the right abstraction level quickly. |
| 4 | + |
| 5 | +## Tier 1: Minimal API (`SimpleDiffViewer`) |
| 6 | + |
| 7 | +**Best for** |
| 8 | + |
| 9 | +- Product teams that need a reliable diff view fast. |
| 10 | +- Typical PR/MR preview pages. |
| 11 | +- Apps where defaults are good enough and maintainability matters more than customization. |
| 12 | + |
| 13 | +**Use this when** |
| 14 | + |
| 15 | +- You only need to pass two texts and a few basic display options. |
| 16 | +- You want the smallest cognitive load for contributors. |
| 17 | + |
| 18 | +**Primary API** |
| 19 | + |
| 20 | +- `original` |
| 21 | +- `modified` |
| 22 | +- `height` |
| 23 | +- `splitView` |
| 24 | +- `showDiffOnly` |
| 25 | +- `contextLines` |
| 26 | +- `hideLineNumbers` |
| 27 | +- `useDarkTheme` |
| 28 | +- `locale` |
| 29 | + |
| 30 | +### Minimal example 1: 基础对比 |
| 31 | + |
| 32 | +```tsx |
| 33 | +import { SimpleDiffViewer } from 'react-virtualized-diff'; |
| 34 | + |
| 35 | +export function BasicDiffExample() { |
| 36 | + return ( |
| 37 | + <SimpleDiffViewer |
| 38 | + original={'line 1\nline 2\nline 3'} |
| 39 | + modified={'line 1\nline 2 changed\nline 3'} |
| 40 | + height={360} |
| 41 | + /> |
| 42 | + ); |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +### Minimal example 2: 大文件虚拟化 |
| 47 | + |
| 48 | +```tsx |
| 49 | +import { SimpleDiffViewer } from 'react-virtualized-diff'; |
| 50 | + |
| 51 | +function buildLargeText(size: number, changedAt: number) { |
| 52 | + return Array.from({ length: size }, (_, i) => |
| 53 | + i === changedAt ? `line ${i + 1} (changed)` : `line ${i + 1}`, |
| 54 | + ).join('\n'); |
| 55 | +} |
| 56 | + |
| 57 | +export function VirtualizedLargeFileExample() { |
| 58 | + const original = buildLargeText(50000, -1); |
| 59 | + const modified = buildLargeText(50000, 24567); |
| 60 | + |
| 61 | + return ( |
| 62 | + <SimpleDiffViewer |
| 63 | + original={original} |
| 64 | + modified={modified} |
| 65 | + height={640} |
| 66 | + contextLines={1} |
| 67 | + showDiffOnly |
| 68 | + /> |
| 69 | + ); |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +## Tier 2: Advanced API (`DiffViewer` / `AdvancedDiffViewer`) |
| 74 | + |
| 75 | +**Best for** |
| 76 | + |
| 77 | +- Code review platforms with domain-specific behaviors. |
| 78 | +- Teams needing tight design-system integration. |
| 79 | +- Scenarios requiring interaction hooks and custom rendering. |
| 80 | + |
| 81 | +**Use this when** |
| 82 | + |
| 83 | +- You need custom line rendering (syntax highlighting, inline widgets). |
| 84 | +- You need line-number gutter interactions. |
| 85 | +- You need custom fold/collapse messaging or styling. |
| 86 | + |
| 87 | +**Primary advanced extension points** |
| 88 | + |
| 89 | +- 自定义行渲染: `renderContent` |
| 90 | +- 语法高亮集成: `renderContent` |
| 91 | +- 行号 gutter 交互: `onLineNumberClick`, `highlightLines`, `linesOffset` |
| 92 | +- 折叠策略: `showDiffOnly`, `contextLines`, `extraLinesSurroundingDiff`, `codeFoldMessageRenderer` |
| 93 | +- 深度样式定制: `styles`, `useDarkTheme` |
| 94 | + |
| 95 | +### Minimal example 3: 可评论行组件嵌入 |
| 96 | + |
| 97 | +```tsx |
| 98 | +import { DiffViewer } from 'react-virtualized-diff'; |
| 99 | + |
| 100 | +function CommentableLine({ line }: { line: string }) { |
| 101 | + return ( |
| 102 | + <span style={{ display: 'inline-flex', gap: 8 }}> |
| 103 | + <span>{line}</span> |
| 104 | + <button type="button">Comment</button> |
| 105 | + </span> |
| 106 | + ); |
| 107 | +} |
| 108 | + |
| 109 | +export function CommentableDiffExample() { |
| 110 | + return ( |
| 111 | + <DiffViewer |
| 112 | + original={'const a = 1\nconst b = 2'} |
| 113 | + modified={'const a = 1\nconst b = 3'} |
| 114 | + renderContent={(line) => <CommentableLine line={line} />} |
| 115 | + onLineNumberClick={(lineId) => { |
| 116 | + // open comment panel by line id |
| 117 | + console.log('comment target:', lineId); |
| 118 | + }} |
| 119 | + height={420} |
| 120 | + /> |
| 121 | + ); |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +## Recommendation matrix |
| 126 | + |
| 127 | +- Start with `SimpleDiffViewer` for most application pages. |
| 128 | +- Move to `DiffViewer` (`AdvancedDiffViewer`) only after a concrete customization requirement appears. |
| 129 | +- Keep one internal wrapper in your codebase if your product repeatedly uses the same advanced options. |
0 commit comments