|
| 1 | +# canvas-draw-text |
| 2 | + |
| 3 | +[](npm-url) |
| 4 | +[![CI status][github-action-image]][github-action-url] |
| 5 | +[](https://codecov.io/gh/Marinerer/jotter) |
| 6 | +[](npm-url) |
| 7 | +[](https://bundlephobia.com/package/canvas-draw-text) |
| 8 | +[](github-url) |
| 9 | + |
| 10 | +[github-url]: https://github.com/Marinerer/jotter/blob/main/libs/drawText |
| 11 | +[npm-url]: https://www.npmjs.com/package/canvas-draw-text |
| 12 | +[github-action-image]: https://img.shields.io/github/actions/workflow/status/Marinerer/jotter/release.yml?style=flat-square |
| 13 | +[github-action-url]: https://github.com/Marinerer/jotter/actions/workflows/release.yml |
| 14 | + |
| 15 | +A utility designed to simplify Canvas text rendering that offers advanced features for text layout, styling, and management on HTML5 Canvas. |
| 16 | + |
| 17 | +> 旨在简化 Canvas 文本渲染的实用工具函数,它为 HTML5 Canvas 上的文本布局、样式和管理提供高级功能。 |
| 18 | +
|
| 19 | +## Features |
| 20 | + |
| 21 | +- ✂️ Automatic Text Wrapping |
| 22 | +- 📰 Text Alignment |
| 23 | +- 📊 Rich Text Styling |
| 24 | +- 🧮 Layout Control |
| 25 | +- 🗳️ Overflow Handling |
| 26 | +- 🌏 Detailed Return Data |
| 27 | + |
| 28 | +## Installation |
| 29 | + |
| 30 | +**npm** |
| 31 | + |
| 32 | +```bash |
| 33 | +npm install canvas-draw-text |
| 34 | +``` |
| 35 | + |
| 36 | +**browser** |
| 37 | + |
| 38 | +``` |
| 39 | +https://cdn.jsdelivr.net/npm/canvas-draw-text/dist/index.min.js |
| 40 | +``` |
| 41 | + |
| 42 | +## Usage |
| 43 | + |
| 44 | +```javascript |
| 45 | +import drawText from 'canvas-draw-text' |
| 46 | + |
| 47 | +// Get your canvas context |
| 48 | +const canvas = document.getElementById('myCanvas') |
| 49 | +const ctx = canvas.getContext('2d') |
| 50 | + |
| 51 | +// Draw text with automatic wrapping |
| 52 | +drawText(ctx, 'Your text here', 10, 10, 300, 200, { |
| 53 | + color: '#333', |
| 54 | + font: '16px Arial', |
| 55 | + textAlign: 'left', |
| 56 | + verticalAlign: 'top', |
| 57 | +}) |
| 58 | +``` |
| 59 | + |
| 60 | +### Extension Method |
| 61 | + |
| 62 | +You can also extend the CanvasRenderingContext2D prototype to use drawText as a method: |
| 63 | + |
| 64 | +```javascript |
| 65 | +import drawText from 'canvas-draw-text' |
| 66 | + |
| 67 | +// Add the drawText method to the CanvasRenderingContext2D prototype |
| 68 | +drawText.use() |
| 69 | + |
| 70 | +// Now you can use it directly on the context |
| 71 | +const canvas = document.getElementById('myCanvas') |
| 72 | +const ctx = canvas.getContext('2d') |
| 73 | + |
| 74 | +ctx.drawText('Your text here', 10, 10, 300, 200, { |
| 75 | + color: '#333', |
| 76 | + textAlign: 'center', |
| 77 | +}) |
| 78 | +``` |
| 79 | + |
| 80 | +## API |
| 81 | + |
| 82 | +### drawText(ctx, text, x, y, width, height, options) |
| 83 | + |
| 84 | +Draws text on a canvas with advanced layout and styling options. |
| 85 | + |
| 86 | +#### Parameters |
| 87 | + |
| 88 | +| Parameter | Type | Default | Description | |
| 89 | +| --------- | ------------------------ | ------------- | --------------------------------- | |
| 90 | +| `ctx` | CanvasRenderingContext2D | _required_ | Canvas 2D context | |
| 91 | +| `text` | string | _required_ | Text to draw | |
| 92 | +| `x` | number | 0 | Left position of the drawing area | |
| 93 | +| `y` | number | 0 | Top position of the drawing area | |
| 94 | +| `width` | number | canvas.width | Width of the drawing area | |
| 95 | +| `height` | number | canvas.height | Height of the drawing area | |
| 96 | +| `options` | object | `{}` | Configuration options (see below) | |
| 97 | + |
| 98 | +#### Options |
| 99 | + |
| 100 | +| Option | Type | Default | Description | |
| 101 | +| ------------------- | -------------- | --------- | ------------------------------------------------------------------------------------- | |
| 102 | +| `padding` | number\|array | 0 | Inner padding. Can be a single number or `[top, right, bottom, left]` | |
| 103 | +| `textAlign` | string | 'left' | Horizontal alignment: 'left', 'center', 'right' | |
| 104 | +| `verticalAlign` | string | 'top' | Vertical alignment: 'top', 'middle', 'bottom' | |
| 105 | +| `font` | string\|object | - | Font settings. String format: '16px Arial' or object: `{size, family, weight, style}` | |
| 106 | +| `color` | string | '#000' | Text color | |
| 107 | +| `backgroundColor` | string | - | Text background color | |
| 108 | +| `backgroundPadding` | number\|array | 0 | Padding around text for background. | |
| 109 | +| `lineHeight` | number | 1.2 | Line height multiplier | |
| 110 | +| `letterSpacing` | number | 0 | Spacing between characters | |
| 111 | +| `wrap` | boolean | true | Whether to automatically wrap text | |
| 112 | +| `overflow` | string | 'visible' | Overflow handling: 'visible', 'hidden' | |
| 113 | +| `textOverflow` | string | '' | Text to display when content is truncated, e.g., `'...' ` | |
| 114 | + |
| 115 | +#### Return Value |
| 116 | + |
| 117 | +The function returns an object with the following properties: |
| 118 | + |
| 119 | +| Property | Type | Description | |
| 120 | +| ----------------- | ------- | -------------------------------------------------- | |
| 121 | +| `totalLines` | number | Total number of lines (including overflow) | |
| 122 | +| `lines` | number | Number of visible lines | |
| 123 | +| `maxTextHeight` | number | Height of all text lines (including overflow) | |
| 124 | +| `maxTextWidth` | number | Width of the widest text line (including overflow) | |
| 125 | +| `textHeight` | number | Height of visible text | |
| 126 | +| `textWidth` | number | Width of visible text | |
| 127 | +| `availableWidth` | number | Available width for drawing (after padding) | |
| 128 | +| `availableHeight` | number | Available height for drawing (after padding) | |
| 129 | +| `overflow` | boolean | Whether text overflow occurred | |
| 130 | + |
| 131 | +## Browser Support |
| 132 | + |
| 133 | +Works in all modern browsers that support Canvas API. The library automatically handles browser compatibility issues for text measurements. |
| 134 | + |
| 135 | +## License |
| 136 | + |
| 137 | +MIT © [Mariner](https://github.com/Marinerer/) |
| 138 | + |
| 139 | +## Contributing |
| 140 | + |
| 141 | +Contributions are welcome! Please feel free to submit a [Pull Request](https://github.com/Marinerer/jotter/pulls). |
0 commit comments