图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载StructuredText是 MuPDF JavaScript 引擎内置于mutool run中用于承载经过分析并分组后的页面文本的核心类型。它的内部数据按块block→ 行line→ 字符char三级层级组织并提供search、highlight、copy、walk以及asText/asHTML/asJSON等实例方法。读懂这一对象你就能在 MuPDF 里实现页内文本检索、按坐标选区复制、按坐标高亮、遍历每个字符以及把结构化文本导出为纯文本、HTML 或 JSON 用于渲染或下游处理。一、获取 StructuredText 实例toStructuredTextStructuredText没有公开构造函数文档明确标注no_new——不能通过new StructuredText()直接创建。要从Page获取实例统一调用Page.prototype.toStructuredText(options)// 基础用法 var sText page.toStructuredText() // 指定结构化文本选项option string var sText page.toStructuredText(preserve-whitespace)options是一个 option string键值对组成的字符串其完整取值见 stext-options 文档例如preserve-images、preserve-spans、preserve-whitespace、collect-styles、clip、clip-rect、segment、table-hunt等。从源码看toStructuredText的 JavaScript 绑定实现位于 ffi_Page_toStructuredText它先调用fz_parse_stext_options解析 option string再调用fz_new_stext_page_from_page生成fz_stext_page最后把它封装成一个带垃圾回收回调ffi_gc_fz_stext_page的 JS userdata 对象注册名为fz_stext_page。也就是说每个 JSStructuredText实例在底层都对应一个fz_stext_page结构。底层数据结构理解各方法行为的前提是理解fz_stext_page的层级。从 structured-text.h 可以看到其组织方式fz_stext_page一个文本页持有mediabox和first_block块链头。文档注明其命名已略显过时因为一个fz_stext_page实际可容纳多页内容如多页合并、水印场景。fz_stext_block块链节点type取值见fz_stext_block_typeFZ_STEXT_BLOCK_TEXT文本块、FZ_STEXT_BLOCK_IMAGE图像块、FZ_STEXT_BLOCK_STRUCT结构块、FZ_STEXT_BLOCK_VECTOR矢量块、FZ_STEXT_BLOCK_GRID表格网格块。文本块内挂first_line/last_line行链图像块挂transform和image。fz_stext_line行wmode标记 0 为水平、1 为垂直持有dir归一化基线方向、bbox以及first_char/last_char字符链。fz_stext_char单个 Unicode 字符含c码点、argb颜色高位为 alpha、origin位置点、quad字符包围四边形、size字号、font指针以及flags位掩码。正因为这个结构是链式 树形的walk等遍历方法才能逐层下发回调。字符的样式信息删除线、下划线、伪粗体等通过fz_stext_char_flags位标记表达。二、search页内文本检索var result sText.search(Hello World!)search在文本中查找needle的所有出现位置返回一个数组其中每个命中match本身是一个数组包含覆盖该匹配文本的一个或多个Quad四边形。也就是说返回类型是Quad 的二维数组。needlestring要查找的文本。options检索选项取值见 search-options 文档如exact精确匹配、regexp按 JS 正则解释 needle、ignore-case忽略大小写、ignore-diacritics忽略变音符、keep-lines、keep-paragraphs、keep-hyphens。maxHits最多返回的命中数默认 500。在源码层面该方法由 ffi_StructuredText_search 实现注册在 方法表StructuredText.search3 个参数。它支持三种options传入方式直接传数字按位标志、传undefined默认FZ_SEARCH_IGNORE_CASE、或传 option string经fz_parse_search_options解析。检索最终调用fz_match_stext_page_cb通过回调 hit_callback 把每次命中的多个Quad逐个push进一个 JS 数组并把该数组追加到结果数组中当命中数达到max_hits默认 500时回调返回 1 终止检索。这与Page.prototype.search(needle, options)的差异值得注意Page.search直接在页面上搜索而StructuredText.search复用已经提取好的结构化文本适合在一次提取后做多次检索的场景。三、highlight按选区返回高亮四边形var result sText.highlight([100, 100], [200, 100])highlight根据选区的起点p和终点q均为Point即[x, y]返回一个Quad数组用于在渲染层绘制选区高亮。参数pPoint选区起点。qPoint选区终点。maxHitsnumber最多返回的命中数默认 500。其实现 ffi_StructuredText_highlight 把两个点转换后调用 C 层的fz_highlight_selection把得到的Quad数组逐个推入 JS 数组返回。该函数在 C API 头文件 structured-text.h 中声明返回落在两个选点之间的行的四边形列表。四、copy按选区复制文本var result sText.copy([100, 100], [200, 100])copy返回由起点p和终点q定义的选区所覆盖的文本返回类型为 string。其实现 ffi_StructuredText_copy 调用 C 层的fz_copy_selectioncrlf 传 0即换行仅用\n把新分配的 UTF-8 字符串包装为 JS string 后释放 C 侧内存。C 侧fz_copy_selection的声明见 structured-text.h它按选区裁剪文本并返回一个 UTF-8 字符串。五、walk遍历块、行与字符walk是访问结构化文本细节最有力的方法。传入一个 walker 回调对象它会按块 → 行 → 字符的层级深度遍历整个结构化文本对每个文本块遍历其每一行文本对每行遍历每个字符对每个块、行或字符walker 上对应的回调方法会被调用。var sText page.toStructuredText() sText.walk({ beginLine: function (bbox, wmode, direction) { console.log(beginLine, bbox, wmode, direction) }, endLine: function () { console.log(endLine) }, beginTextBlock: function (bbox) { console.log(beginTextBlock, bbox) }, endTextBlock: function () { console.log(endTextBlock) }, beginStruct: function (standard, raw, index) { console.log(beginStruct, standard, raw, index) }, endStruct: function () { console.log(endStruct) }, onChar: function (utf, origin, font, size, quad, argb, flags) { console.log(onChar, utf, origin, font, size, quad, argb, flags) }, onImageBlock: function (bbox, transform, image) { console.log(onImageBlock, bbox, transform, image) }, onVector: function (bbox, flags, argb) { console.log(onVector, bbox, flags, argb) }, })各回调参数含义对应底层 C 结构字段beginLine(bbox, wmode, direction)/endLine()进入/离开一行。wmode0水平、1垂直direction为归一化基线方向向量对应fz_stext_line的dir。beginTextBlock(bbox)/endTextBlock()进入/离开一个文本块。beginStruct(standard, raw, index)/endStruct()进入/离开一个结构节点对应带结构树PDF structure tree的内容standard为标准化结构类型、raw为文档自定义类型、index为同级序号。onChar(utf, origin, font, size, quad, argb, flags)处理单个字符。utf为码点origin为字符原点size为字号quad为字符包围四边形argb为颜色flags为样式位掩码如StructuredText.FLAGS_STRIKEOUT、FLAGS_UNDERLINE、FLAGS_BOLD等见 枚举注册。onImageBlock(bbox, transform, image)遇到图像块时回调transform为该图像的变换矩阵。onVector(bbox, flags, argb)遇到矢量内容时回调flags可判断是否为描边/矩形/高亮/下划线/删除线等对应fz_stext_vector_flags。从源码看walk的实现是 ffi_StructuredText_walk它取出实例对应的fz_stext_page从其first_block开始交给内部的stext_walk递归驱动上述各回调。这也解释了为何回调能按层级成对出现begin/end底层块、行、结构都是链表/树遍历即沿链前进并在切换时触发对应 begin/end。六、序列化导出asText / asHTML / asJSON这三个方法把结构化文本导出为不同格式方便渲染或传给下游系统。asText()纯文本var text sText.asText()返回结构化文本的纯文本表示string。其实现 ffi_StructuredText_asText 默认调用fz_print_stext_page_as_text输出若传入了扁平化标志则改走fz_new_buffer_from_flattened_stext_page用于按keep-lines/keep-paragraphs等语义换行扁平化。asHTML(id)HTML 渲染var html sText.asHTML(0)返回一段 HTML 字符串其中包含文本的 HTML 渲染。参数idnumber用于给最外层 div 的id编号格式为page id便于在页面中区分多页内容。其实现 ffi_StructuredText_asHTML 调用 C 层fz_print_stext_page_as_html。该 HTML 是可视化visual输出与 C API 中另有提供的 XHTML语义输出相区别。asJSON(scale)JSON 序列化var data JSON.parse(page.toStructuredText(preserve-spans).asJSON())返回表示结构化文本数据的 JSON 字符串是walk()所提供信息的一个简化序列化。参数scalenumber可选用于把所有坐标乘以一个缩放因子。注意必须用preserve-spans选项提取结构化文本否则若忘记设置该选项同一行中间出现的字体变化不会出现在 JSON 输出中。JSON 遵循如下 schemaTypeScript 类型标注type StructuredTextPage { blocks: StructuredTextBlock[] } type StructuredTextBlock { type: image | text, bbox: { x: number, y: number, w: number, h: number }, lines: StructuredTextLine[], } type StructuredTextLine { wmode: 0 | 1, // 0horizontal, 1vertical bbox: { x: number, y: number, w: number, h: number }, font: { name: string, family: serif | sans-serif | monospace, weight: normal | bold, style: normal | italic, size: number }, // text origin point for first character in line x: number, y: number, text: string }其实现 ffi_StructuredText_asJSON 把scale传入 C 层fz_print_stext_page_as_json在内存 buffer 中生成 JSON 后以字符串返回。七、方法与底层调用链小结从源码可以确认各 JS 方法到 C 实现的映射关系JS 绑定均位于 source/tools/murun.cJS 方法底层 C 调用说明toStructuredText(options)Pagefz_parse_stext_optionsfz_new_stext_page_from_page生成fz_stext_page注册为 JS userdatasearch(needle, options, maxHits)fz_match_stext_page_cb默认FZ_SEARCH_IGNORE_CASE默认最多 500 命中highlight(p, q, maxHits)fz_highlight_selection返回选区内的行四边形copy(p, q)fz_copy_selection返回选区文本UTF-8walk(walker)stext_walk内部递归按块→行→字符层级驱动回调asText()fz_print_stext_page_as_text纯文本输出asHTML(id)fz_print_stext_page_as_html可视化 HTML 输出asJSON(scale)fz_print_stext_page_as_jsonJSON 输出需preserve-spans相关文档与源码可继续深入选项参考stext-options、search-options创建入口Page.toStructuredText 文档数据与 C API 声明include/mupdf/fitz/structured-text.hJavaScript 绑定实现source/tools/murun.c掌握StructuredText后你可以在 MuPDF 的 JS 运行时中把页面文本提取为可检索、可按坐标选区复制/高亮、可逐字符遍历、并可序列化为纯文本/HTML/JSON 的结构化数据从而支撑全文检索、文本导出、内容分析与无障碍渲染等常见需求。赞分享图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载相关推荐MuPDF JavaScript Font 对象全解在 SumatraPDF 内嵌的 MuPDF 中创建与使用字体MuPDF JavaScript Font 对象全解在 SumatraPDF 内嵌的 MuPDF 中创建与使用字体 导读 本文围绕本仓库所携带的 MuPDF桌面应用文档MuPDF JavaScript 绑定Image 图像对象完整 API 指南MuPDF JavaScript 绑定Image 图像对象完整 API 指南 本篇指南以 MuPDF 官方 JavaScript 绑定文档 docs/ref图形学图像处理MuPDF JavaScript PDFGraftMap 深度指南跨文档复制 PDF 对象与页面MuPDF JavaScript PDFGraftMap 深度指南跨文档复制 PDF 对象与页面 导读 PDFGraftMap 是 MuPDF JavaScr图形学图像处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 16:59:35 · 阅读 1.2k MuPDF JavaScript API：StructuredText 结构化文本对象详解
图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载StructuredText是 MuPDF JavaScript 引擎内置于mutool run中用于承载经过分析并分组后的页面文本的核心类型。它的内部数据按块block→ 行line→ 字符char三级层级组织并提供search、highlight、copy、walk以及asText/asHTML/asJSON等实例方法。读懂这一对象你就能在 MuPDF 里实现页内文本检索、按坐标选区复制、按坐标高亮、遍历每个字符以及把结构化文本导出为纯文本、HTML 或 JSON 用于渲染或下游处理。一、获取 StructuredText 实例toStructuredTextStructuredText没有公开构造函数文档明确标注no_new——不能通过new StructuredText()直接创建。要从Page获取实例统一调用Page.prototype.toStructuredText(options)// 基础用法 var sText page.toStructuredText() // 指定结构化文本选项option string var sText page.toStructuredText(preserve-whitespace)options是一个 option string键值对组成的字符串其完整取值见 stext-options 文档例如preserve-images、preserve-spans、preserve-whitespace、collect-styles、clip、clip-rect、segment、table-hunt等。从源码看toStructuredText的 JavaScript 绑定实现位于 ffi_Page_toStructuredText它先调用fz_parse_stext_options解析 option string再调用fz_new_stext_page_from_page生成fz_stext_page最后把它封装成一个带垃圾回收回调ffi_gc_fz_stext_page的 JS userdata 对象注册名为fz_stext_page。也就是说每个 JSStructuredText实例在底层都对应一个fz_stext_page结构。底层数据结构理解各方法行为的前提是理解fz_stext_page的层级。从 structured-text.h 可以看到其组织方式fz_stext_page一个文本页持有mediabox和first_block块链头。文档注明其命名已略显过时因为一个fz_stext_page实际可容纳多页内容如多页合并、水印场景。fz_stext_block块链节点type取值见fz_stext_block_typeFZ_STEXT_BLOCK_TEXT文本块、FZ_STEXT_BLOCK_IMAGE图像块、FZ_STEXT_BLOCK_STRUCT结构块、FZ_STEXT_BLOCK_VECTOR矢量块、FZ_STEXT_BLOCK_GRID表格网格块。文本块内挂first_line/last_line行链图像块挂transform和image。fz_stext_line行wmode标记 0 为水平、1 为垂直持有dir归一化基线方向、bbox以及first_char/last_char字符链。fz_stext_char单个 Unicode 字符含c码点、argb颜色高位为 alpha、origin位置点、quad字符包围四边形、size字号、font指针以及flags位掩码。正因为这个结构是链式 树形的walk等遍历方法才能逐层下发回调。字符的样式信息删除线、下划线、伪粗体等通过fz_stext_char_flags位标记表达。二、search页内文本检索var result sText.search(Hello World!)search在文本中查找needle的所有出现位置返回一个数组其中每个命中match本身是一个数组包含覆盖该匹配文本的一个或多个Quad四边形。也就是说返回类型是Quad 的二维数组。needlestring要查找的文本。options检索选项取值见 search-options 文档如exact精确匹配、regexp按 JS 正则解释 needle、ignore-case忽略大小写、ignore-diacritics忽略变音符、keep-lines、keep-paragraphs、keep-hyphens。maxHits最多返回的命中数默认 500。在源码层面该方法由 ffi_StructuredText_search 实现注册在 方法表StructuredText.search3 个参数。它支持三种options传入方式直接传数字按位标志、传undefined默认FZ_SEARCH_IGNORE_CASE、或传 option string经fz_parse_search_options解析。检索最终调用fz_match_stext_page_cb通过回调 hit_callback 把每次命中的多个Quad逐个push进一个 JS 数组并把该数组追加到结果数组中当命中数达到max_hits默认 500时回调返回 1 终止检索。这与Page.prototype.search(needle, options)的差异值得注意Page.search直接在页面上搜索而StructuredText.search复用已经提取好的结构化文本适合在一次提取后做多次检索的场景。三、highlight按选区返回高亮四边形var result sText.highlight([100, 100], [200, 100])highlight根据选区的起点p和终点q均为Point即[x, y]返回一个Quad数组用于在渲染层绘制选区高亮。参数pPoint选区起点。qPoint选区终点。maxHitsnumber最多返回的命中数默认 500。其实现 ffi_StructuredText_highlight 把两个点转换后调用 C 层的fz_highlight_selection把得到的Quad数组逐个推入 JS 数组返回。该函数在 C API 头文件 structured-text.h 中声明返回落在两个选点之间的行的四边形列表。四、copy按选区复制文本var result sText.copy([100, 100], [200, 100])copy返回由起点p和终点q定义的选区所覆盖的文本返回类型为 string。其实现 ffi_StructuredText_copy 调用 C 层的fz_copy_selectioncrlf 传 0即换行仅用\n把新分配的 UTF-8 字符串包装为 JS string 后释放 C 侧内存。C 侧fz_copy_selection的声明见 structured-text.h它按选区裁剪文本并返回一个 UTF-8 字符串。五、walk遍历块、行与字符walk是访问结构化文本细节最有力的方法。传入一个 walker 回调对象它会按块 → 行 → 字符的层级深度遍历整个结构化文本对每个文本块遍历其每一行文本对每行遍历每个字符对每个块、行或字符walker 上对应的回调方法会被调用。var sText page.toStructuredText() sText.walk({ beginLine: function (bbox, wmode, direction) { console.log(beginLine, bbox, wmode, direction) }, endLine: function () { console.log(endLine) }, beginTextBlock: function (bbox) { console.log(beginTextBlock, bbox) }, endTextBlock: function () { console.log(endTextBlock) }, beginStruct: function (standard, raw, index) { console.log(beginStruct, standard, raw, index) }, endStruct: function () { console.log(endStruct) }, onChar: function (utf, origin, font, size, quad, argb, flags) { console.log(onChar, utf, origin, font, size, quad, argb, flags) }, onImageBlock: function (bbox, transform, image) { console.log(onImageBlock, bbox, transform, image) }, onVector: function (bbox, flags, argb) { console.log(onVector, bbox, flags, argb) }, })各回调参数含义对应底层 C 结构字段beginLine(bbox, wmode, direction)/endLine()进入/离开一行。wmode0水平、1垂直direction为归一化基线方向向量对应fz_stext_line的dir。beginTextBlock(bbox)/endTextBlock()进入/离开一个文本块。beginStruct(standard, raw, index)/endStruct()进入/离开一个结构节点对应带结构树PDF structure tree的内容standard为标准化结构类型、raw为文档自定义类型、index为同级序号。onChar(utf, origin, font, size, quad, argb, flags)处理单个字符。utf为码点origin为字符原点size为字号quad为字符包围四边形argb为颜色flags为样式位掩码如StructuredText.FLAGS_STRIKEOUT、FLAGS_UNDERLINE、FLAGS_BOLD等见 枚举注册。onImageBlock(bbox, transform, image)遇到图像块时回调transform为该图像的变换矩阵。onVector(bbox, flags, argb)遇到矢量内容时回调flags可判断是否为描边/矩形/高亮/下划线/删除线等对应fz_stext_vector_flags。从源码看walk的实现是 ffi_StructuredText_walk它取出实例对应的fz_stext_page从其first_block开始交给内部的stext_walk递归驱动上述各回调。这也解释了为何回调能按层级成对出现begin/end底层块、行、结构都是链表/树遍历即沿链前进并在切换时触发对应 begin/end。六、序列化导出asText / asHTML / asJSON这三个方法把结构化文本导出为不同格式方便渲染或传给下游系统。asText()纯文本var text sText.asText()返回结构化文本的纯文本表示string。其实现 ffi_StructuredText_asText 默认调用fz_print_stext_page_as_text输出若传入了扁平化标志则改走fz_new_buffer_from_flattened_stext_page用于按keep-lines/keep-paragraphs等语义换行扁平化。asHTML(id)HTML 渲染var html sText.asHTML(0)返回一段 HTML 字符串其中包含文本的 HTML 渲染。参数idnumber用于给最外层 div 的id编号格式为page id便于在页面中区分多页内容。其实现 ffi_StructuredText_asHTML 调用 C 层fz_print_stext_page_as_html。该 HTML 是可视化visual输出与 C API 中另有提供的 XHTML语义输出相区别。asJSON(scale)JSON 序列化var data JSON.parse(page.toStructuredText(preserve-spans).asJSON())返回表示结构化文本数据的 JSON 字符串是walk()所提供信息的一个简化序列化。参数scalenumber可选用于把所有坐标乘以一个缩放因子。注意必须用preserve-spans选项提取结构化文本否则若忘记设置该选项同一行中间出现的字体变化不会出现在 JSON 输出中。JSON 遵循如下 schemaTypeScript 类型标注type StructuredTextPage { blocks: StructuredTextBlock[] } type StructuredTextBlock { type: image | text, bbox: { x: number, y: number, w: number, h: number }, lines: StructuredTextLine[], } type StructuredTextLine { wmode: 0 | 1, // 0horizontal, 1vertical bbox: { x: number, y: number, w: number, h: number }, font: { name: string, family: serif | sans-serif | monospace, weight: normal | bold, style: normal | italic, size: number }, // text origin point for first character in line x: number, y: number, text: string }其实现 ffi_StructuredText_asJSON 把scale传入 C 层fz_print_stext_page_as_json在内存 buffer 中生成 JSON 后以字符串返回。七、方法与底层调用链小结从源码可以确认各 JS 方法到 C 实现的映射关系JS 绑定均位于 source/tools/murun.cJS 方法底层 C 调用说明toStructuredText(options)Pagefz_parse_stext_optionsfz_new_stext_page_from_page生成fz_stext_page注册为 JS userdatasearch(needle, options, maxHits)fz_match_stext_page_cb默认FZ_SEARCH_IGNORE_CASE默认最多 500 命中highlight(p, q, maxHits)fz_highlight_selection返回选区内的行四边形copy(p, q)fz_copy_selection返回选区文本UTF-8walk(walker)stext_walk内部递归按块→行→字符层级驱动回调asText()fz_print_stext_page_as_text纯文本输出asHTML(id)fz_print_stext_page_as_html可视化 HTML 输出asJSON(scale)fz_print_stext_page_as_jsonJSON 输出需preserve-spans相关文档与源码可继续深入选项参考stext-options、search-options创建入口Page.toStructuredText 文档数据与 C API 声明include/mupdf/fitz/structured-text.hJavaScript 绑定实现source/tools/murun.c掌握StructuredText后你可以在 MuPDF 的 JS 运行时中把页面文本提取为可检索、可按坐标选区复制/高亮、可逐字符遍历、并可序列化为纯文本/HTML/JSON 的结构化数据从而支撑全文检索、文本导出、内容分析与无障碍渲染等常见需求。赞分享图形学图像处理【免费下载链接】mupdfmupdf mirror项目地址https://gitcode.com/gh_mirrors/mu/mupdf点击查看免费下载相关推荐MuPDF JavaScript Font 对象全解在 SumatraPDF 内嵌的 MuPDF 中创建与使用字体MuPDF JavaScript Font 对象全解在 SumatraPDF 内嵌的 MuPDF 中创建与使用字体 导读 本文围绕本仓库所携带的 MuPDF桌面应用文档MuPDF JavaScript 绑定Image 图像对象完整 API 指南MuPDF JavaScript 绑定Image 图像对象完整 API 指南 本篇指南以 MuPDF 官方 JavaScript 绑定文档 docs/ref图形学图像处理MuPDF JavaScript PDFGraftMap 深度指南跨文档复制 PDF 对象与页面MuPDF JavaScript PDFGraftMap 深度指南跨文档复制 PDF 对象与页面 导读 PDFGraftMap 是 MuPDF JavaScr图形学图像处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考