Skip to content

Commit 11b3fa2

Browse files
authored
feat(drawText): Add canvas-draw-text for advanced text rendering (#12)
* feat(drawText): Add canvas-draw-text library for advanced text rendering * feat(drawText): Add text background color and padding support in drawText * perf(drawText): Refactor drawText BgPadding & optimize padding handling * feat(drawText): Add tests and fix prototype extension check * perf(drawText): Refactor and organize drawText tests for clarity and structure * docs(drawText): Update README and package.json
1 parent bb51434 commit 11b3fa2

File tree

7 files changed

+1384
-0
lines changed

7 files changed

+1384
-0
lines changed

libs/drawText/README.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# canvas-draw-text
2+
3+
[![version](https://img.shields.io/npm/v/canvas-draw-text?style=flat-square)](npm-url)
4+
[![CI status][github-action-image]][github-action-url]
5+
[![codecov](https://codecov.io/gh/Marinerer/jotter/graph/badge.svg?token=G7QXEHCEXW)](https://codecov.io/gh/Marinerer/jotter)
6+
[![downloads](https://img.shields.io/npm/dm/canvas-draw-text?style=flat-square)](npm-url)
7+
[![size](https://img.shields.io/bundlephobia/minzip/canvas-draw-text?style=flat-square)](https://bundlephobia.com/package/canvas-draw-text)
8+
[![license](https://img.shields.io/npm/l/canvas-draw-text?style=flat-square)](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

Comments
 (0)