画布文本段落

Canvas Text paragraph是一个JavaScript库，旨在促进在HTML5画布元素上呈现格式化段落。它提供了在画布内管理文本对齐、缩进、行间距和垂直定位的功能。

安装

你可以通过npm安装Canvas Text段落：

npm install @sch39/canvas-text-paragraphs

或者来自unpkg

<script src="https://unpkg.com/@sch39/canvas-text-paragraphs@latest/dist/index.umd.js"></script>

该脚本公开了全局函数 canvasTextParagraphs.

使用

导入库

import canvasTextParagraphs from '@sch39/canvas-text-paragraphs'

例子

import canvasTextParagraphs from '@sch39/canvas-text-paragraphs';

const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');

const text = `
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Nulla facilisi. Integer id elit varius, commodo tortor eget,
lacinia ligula. Ut interdum nisi non dui pretium faucibus.
`;

canvasTextParagraphs(text, ctx, {
  align: 'center',
  verticalAlign: 'middle',
  spaceBeforeParagraph: 20,
  spaceAfterParagraph: 20,
  indent: {
    type: 'firstLine',
    by: 40,
  },
});

打印稿

类型定义捆绑在一起(index.d.ts),没有 @types 包需要:

import canvasTextParagraphs from '@sch39/canvas-text-paragraphs'
import type { Options } from '@sch39/canvas-text-paragraphs'

const ctx = (document.getElementById('myCanvas') as HTMLCanvasElement).getContext('2d')!

const options: Options = {
  width: 400,
  align: 'justify',
  indent: { type: 'firstLine', by: 4 },
}

canvasTextParagraphs('Hello world', ctx, options)

演示

链接: 点击这里

现场演示: 点击这里

函数参数

• 文本 （string）：要呈现的文本内容。
• ctx （CanvasRenderingContext2D）：画布渲染上下文。
• 选项 （object）：可选配置对象，具有以下属性：
  • 宽度 （number或‘auto’，默认值：‘auto’）：文本框的宽度。 'auto' =画布的其余部分 xStart.
  • 高度 （number或‘auto’，默认值：‘auto’）：文本框的高度。 'auto' =画布的其余部分 yStart。下面的线条 yStart + height 没有画出来。
  • xStart （数字，默认值：0）：文本框的左边缘。
  • yStart （数字，默认值：0）：文本框的上边缘。
  • 对齐 （string, default: 'left‘）：水平文本对齐（’left', 'center', 'right', 'justify'）。
  • verticalAlign （string, default: 'top‘）：垂直文本对齐（’top', 'middle', 'bottom'）。
  • 基线 （string, default: 'top‘）：文本基线对齐（’top', 'hanging', 'middle', 'alphabetic', 'ideographic', 'bottom'）。
  • spaceBeforeParagraph （数字，默认值：0）：每段前的空格。
  • spaceAfterParagraph （数字，默认值：0）：每个段落后面的空格。
  • lineSpacing （number或‘auto’， default: 'auto'）：行间距因子（乘以行高），或 'auto' 用于自动间隔。
  • 缩进 （object）：与默认值合并，所以你可以只传递你需要的键(例如： { type: 'firstLine' } 使用 by: 0， { by: 4 } 使用 type: 'none'）。
    • 类型 （string, default: 'none‘）：缩进类型（’none', 'firstLine', 'hanging'）。
    • 由 （number，默认值：0）：缩进量，表示当前字体中的空格字符数。

文本框为 [xStart, xStart + width] x [yStart, yStart + height]。自动换行, align， indent 和 verticalAlign 都在这个方框内计算。

行为笔记

• 段落之间用 \n。每一段都是逐字剪裁和包装的；一个比 width 不裂开，溢出盒子。
• 段落的最后一行永远不会对齐（它是左对齐的）。
• 画布状态是隔离的： textBaseline 和 textAlign 在绘制时设置并在之后恢复，因此您自己的值保持不变。集 ctx.font 和 ctx.fillStyle 之前调用。

错误

无效输入引发 Error 带着信息 Invalid <name>例如： Invalid text， Invalid ctx， Invalid Align， Invalid width 或者 Invalid indent.by. ctx 一定是。 CanvasRenderingContext2D.

开发

npm install
npm test        # vitest
npm run build   # dist/ (cjs, es, umd)
npm run dev     # vite dev server

从1.x迁移

在2.0.0, width 和 height 是 大小 文本框的。在1。X它们是绝对的右/底边缘(xStart + size）。

• 如果 xStart 和 yStart 是 0 （或省略），什么都没有改变。
• 如果你设置 xStart/yStart 一起 width/height，从旧值中减去起始值：

// 1.x: right edge at x = 300, bottom edge at y = 200
canvasTextParagraphs(text, ctx, { xStart: 50, yStart: 20, width: 300, height: 200 })

// 2.0.0: same box
canvasTextParagraphs(text, ctx, { xStart: 50, yStart: 20, width: 250, height: 180 })

• 'auto' 仍然填满画布，现在从 xStart/yStart.
• verticalAlign: 'middle' | 'bottom' 现在中心/底部在框内，而不是相对于画布原点。

1.1.0以来的其他行为变化：

• 完全符合框宽的行不再提前换行（不再测量尾随空间），因此换行可能与1.x略有不同。
• indent 与其默认值合并； { type: 'firstLine' } 没有 by 不再投掷。
• textBaseline 和 textAlign 将在每次调用后恢复您的上下文。
• UMD构建只公开全局 canvasTextParagraphs，现在可以在任何地方导入ES构建 self 未定义（节点，SSR）。

许可证

本项目使用麻省理工学院许可协议。看到 许可证 文件查看详细信息。