@giraffesyo/ 下标记
在Node.js和浏览器中将文档转换为Markdown:PDF,DOCX,XLSX,PPTX,DOC(Word 97–2003),HTML,CSV,ZIP档案,和Plaintext. 这是纯粹的去 下标记 库,用一个小的 TypeScript API 包裹。 一切都在当地运行,没有网络呼叫.
安装
npm install @giraffesyo/downmark
需要18号节点或任何现代浏览器.
两次执行,一次API
convert() 运行相同的 Go 代码 无论是哪种方式, 但有两个建筑它
和包之间选择每个主机 :
- 本地二进制,每平面包件内装船
(单位:千美元)
@giraffesyo/downmark-linux-x645个兄弟姐妹) 宣布为可选依赖。 npm 只安装一个匹配 主办单位os编号 :cpu并跳过其余。 没有下载步骤也没有 邮购脚本: 二进制在柏油球内,所以npm install在一个代理 和一个空中集束,pnpm deploy携带 锁被钉住. - 网络大会建设,捆绑在这个包中,在没有的情况下使用
应用平台软件包——浏览器,未列出的平台,安装器
运行与
--omit=optional。 。 。 .
他们也一样回来 { markdown, title, warnings } 对于相同的输入。 这个
本地路径更快, 运行转换到另一个进程而不是打开
事件循环,是唯一可以做到的 OCR (英语)。 。 。 .
没有其他关于你的代码改变.
import { binaryPath } from "@giraffesyo/downmark";
binaryPath(); // "/…/node_modules/@giraffesyo/downmark-darwin-arm64/bin/downmark", or null on wasm
所支持的平台:linux,darwin,并使用x64和arm64的win32. 前进 二进制是静态的,所以Linux包覆盖了glibc和musl(高山) 一样.
设定 DOWNMARK_FORCE_WASM=1,或打电话 init({ preferWasm: true }),忽略
一个已安装的二进制——用于比较两者. DOWNMARK_BIN=/path/to/downmark
在您自己的二进制中点出; 如果不存在, 调用比方
而不是悄悄地掉下来.
用法(节点)
import { readFile } from "node:fs/promises";
import { convert } from "@giraffesyo/downmark";
const data = await readFile("report.docx");
const { markdown, title } = await convert(data, { filename: "report.docx" });
console.log(markdown);
通用JS同样工作:
const { convert } = require("@giraffesyo/downmark");
在原生路径上,每次转换都产出二进制(约5-10 ms of ),而没有任何内容被载入您的进程。 在原地的道路上 模块在第一次呼叫时被懒散地装入并被缓存,所以随后 调用重复使用同一实例.
用法 (浏览器)
import { convert } from "@giraffesyo/downmark";
const file = input.files[0];
const data = new Uint8Array(await file.arrayBuffer());
const { markdown } = await convert(data, { filename: file.name });
浏览器没有产入过程,所以这总是被堆积而成.
浏览器构建抓取 downmark.wasm 相对于通过 new URL("./downmark.wasm", import.meta.url). Bundlers 了解该模式的 (Vite, Webpack 5, Rollup with the url 插件) 自动将被体复制到构建输出中.
如果你的捆绑者不这样做,指 init() 在第一次通话前
// Vite
import wasmUrl from "@giraffesyo/downmark/downmark.wasm?url";
import { init, convert } from "@giraffesyo/downmark";
await init(wasmUrl);
init() 接受字符串 URL/ path, a URL,一个 ArrayBuffer编号 :Uint8Array页:1 Response,或预编译 WebAssembly.Module。 。 。 .
没有捆绑? 见 example/browser.html 为平地 <script type="module"> 页 次.
服务提示 : 原为~12 MB 未压缩。 给它服务 Content-Encoding: br 或者说 gzip (≈-4-6 MB过线)和a Content-Type: application/wasm 标题如此 WebAssembly.instantiateStreaming 踢入( 如果MIME 类型错误, 包会回到缓冲) .
API 密码
convert(data, options?) → Promise<{ markdown, title, warnings }>
data 是一个 Uint8Array 或者说 ArrayBuffer。所有选项都是可选的,但您给出的提示越多,格式检测就越好:
| 选项 | 类型 | 含义 |
|---|---|---|
filename | string | 源文件的基名,例如:. "report.docx" |
mimeType | string | 无参数的媒体类型,例如:. "application/pdf" |
extension | string | 文件扩展名( 正常化为小写并带有前缀) |
charset | string | IANA 字符集名称用于文本输入, 例如 . "shift_jis" |
keepDataUris | boolean | 饱满 data: URIs (HTML) / 嵌入图像作为数据 URIs (DOCX) |
resultLimit | number | 拒绝大于此数字节的结果 RESULT_TOO_LARGE |
ocr | object | 使用 OCR 引擎读取扫描的 PDF 页面(下级; 仅本地二进制 |
warnings 报告转换损失,当转换损失时为空
没什么 返回警告的转换仍然成功——Markdown是
有用,但并不是所有的输入.
const { markdown, warnings } = await convert(data, { filename: "scan.pdf" });
for (const w of warnings) {
// { converter: "pdf", code: "incomplete", location: "page 12", message: "..." }
console.warn(`${w.code}: ${w.message}`);
}
code 无论是 "incomplete" (所持有的输入内容在
产出)或 "skipped" (整个单位从未尝试).
扫描的 PDF OCR
被扫描的页面持有图像,而不是文本,所以从
他们。 过 ocr 将这些页面交给OCR引擎:
const { markdown } = await convert(data, {
filename: "scan.pdf",
ocr: { engine: "tesseract", lang: "eng", maxPages: 30 },
});
| 外地 | 类型 | 含义 |
|---|---|---|
engine | "tesseract" | 要求。 要运行的引擎; 必须安装 |
bin | string | 运行此可执行文件而不是打开 PATH |
lang | string | 语法中的语言,例如:. "eng" 或者说 "eng+deu" |
minConfidence | number | 将单词从此下移, 在 Tesseract 的 0- 100 比例上 |
policy | "textless" | "thin" | "images" | 没有自己文本的页面( 默认) , 也可以在打字头下扫描, 或者每页画一幅图像 |
minGlyphs | number | 与 policy: "thin",一个页面需要算作排字; 50 默认 |
maxPages | number | 每个文件最多有这么多页的OCR; 0 无限制 |
pageTimeoutMs | number | 这么长时间后放弃一页 |
timeoutMs | number | 这么长时间之后 放弃整个文件的OCR |
页面可以是扫描而不带文本:传真或签名表格
搭载打字头——日期戳,出行行,页码——
在身体的一幅图上 单独取出那个头像.
policy: "thin" 也读这些,将任何页面交给引擎
少于 minGlyphs 画出图像的格言,同时留下页
仅用自己的文本层. policy: "images" 读取每一页
绘制图像,包括类型文档中的数字.
没有 OCR 引擎 : engine: "tesseract" 运行 a
语法 您已安装
你自己来 OCR大约每页花费一秒钟, 这就是为什么它关闭,除非
问及预算为何存在.
填入的页面 OCR 在 Markdown 中标出 HTML 注释
(单位:千美元)<!-- downmark: page 1 includes OCR text -->:OCR文本是读取
墨水而不是文档本身的字符, 以及不能
告诉两者不能有不同的重量.
这需要本地的二进制——dem不能执行一个程序. 没有
已安装, 已通过 ocr 拒绝方式 NATIVE_REQUIRED 而不是说
返回时会悄悄地丢失其扫描页.
binaryPath() → string | null
下一个本地二进制 convert() 会运行,或 null 当此主机
滚回原地去 对于更愿意执行CLI的来电者
他们自己接受 -json 并写入此软件包中相同的对象
返回.
canConvert(hints) → Promise<boolean>
格式特定转换器是否声称提示所描述的格式(仅从提示判断,没有内容嗅取). false 这并不意味着 convert() 必须失败;它可能仍然会按其字节对输入进行分类,或者返回到纯文本中.
init(source?) → Promise<void>
可选性,关于只执行问题. convert()编号 :canConvert()
默认初始化; 调用 init() 以覆盖原点
(见上面的 " 捆绑方 " ),在这种情况下,它必须在第一次谈判之前运行
转换。 在一个使用本地二进制的主机上,没有什么需要它.
它也接受一个选项对象:
await init({ wasm: wasmUrl, preferWasm: true });
preferWasm: true 使每一个转换都使用相机,即使有一个平台
软件包已安装.
version() → Promise<string>
下印版的被子从.
canConvert() 财务报告和审定财务报表 version() 从原地回答,即使当地人
安装了二进制, 并支付加载费 。 一个在本土路上的呼叫者
两者都不能跳过: convert() 分类输入本身,
财务报告和审定财务报表 binaryPath() 命名一个回答的二进制 -version。 。 。 .
错误
所有失败均以 DownmarkError 携带 code数字 :
| 代码 | 含义 |
|---|---|
UNSUPPORTED_FORMAT | 没有转换器接受任何解释下的输入 |
INPUT_TOO_LARGE | 转换器的硬输入预算被突破 |
RESULT_TOO_LARGE | 超过结果 resultLimit |
CONVERSION_FAILED | 转换器接受输入, 但每次尝试都失败 |
NATIVE_REQUIRED | 呼叫需要本地二进制, 而这个主机没有 |
INTERNAL | 错误的参数或出乎意料的内部失败 |
CONVERSION_FAILED 拒绝是 ConversionFailedError 实例 attempts 数组列出每个尝试过的转换器及其失败的原因 :
import { convert, ConversionFailedError } from "@giraffesyo/downmark";
try {
await convert(data, { filename: "broken.pdf" });
} catch (err) {
if (err instanceof ConversionFailedError) {
for (const a of err.attempts) console.error(`${a.converter}: ${a.message}`);
}
}
说明和限制
- 在tham上,转换为CPU绑定并被单行读取. 一个大的PDF屏蔽了它运行的线程,所以在一个浏览器UI中,在一个Web Worker内部运行转换,以保持页面的响应. 没有
timeout选项,因为忙碌的原案例不能被预先阻止。 原生路径没有这个问题:工作发生在另一个过程中,事件循环保持自由. - 非常大的 XLSX 部件 : 包含大于 16 MiB 的单个内部部件的工作簿会触发 Excel 库的溢出到磁盘路径, 它在 ism( 没有文件系统) 上失败 。 此类文件以
CONVERSION_FAILED。 。 。 . - 原物实例按进程/页数共享。 转换可以同时发布,但一次执行一次. 原生转化是独立的过程,确实平行运行.
- 平台软件包是一个执行细节. 取决于
@giraffesyo/downmark从来没有@giraffesyo/downmark-<platform>直接说.
发展
从 repo 根所建 :
make js-test # build wasm + TS + the binary, run the Node test suite
make wasm 编译 wasm/main.go 改为 js/dist/downmark.wasm 刷新时 js/vendor/wasm_exec.js 从本地的Go工具链. make js-bin 正在建设 cmd/downmark 输入 js/.bin,这是本地测试的结果;没有它,他们跳过.
平台套件在发布时间构建,没有承诺:
goreleaser build --snapshot --clean # dist/downmark_<goos>_<goarch>*/
node js/scripts/stage-npm-release.mjs --version 1.2.3
写着 js/npm/<platform>/ 从这些二进制和邮票的版本
和六个 optionalDependencies 输入 js/package.json。依赖关系
产生而不是承诺,因为 npm ci 验证
package.json 以锁定文件为对象, 并发布名称版本
——所以每一个干净的安装都会失败. 也没有
产出意在承付; .github/scripts/check-npm-packages.sh
在CI中运行相同的脚本来保持它诚实.