桌面应用【免费下载链接】grampsSource code for Gramps Genealogical program项目地址https://gitcode.com/gh_mirrors/gr/gramps点击查看免费下载导读本文围绕 Gramps 源码中 docs/html.rst 所定义的Html类位于 gramps/plugins/lib/libhtml.py系统讲解这一基于 Pythonlist构建的 HTML 文档树 API。作为 Gramps「叙事网页Narrative Web」报告的核心 HTML 生成层Html类负责把家谱数据渲染成结构化、可缩进、可定制的 XHTML/HTML5 页面。读完本文你将掌握Html类的完整构造参数、树操作算子、页面工厂方法与输出机制并了解它与HtmlBackend、libhtmlconst等辅助模块的分工以及它如何在gramps/plugins/webreport/的真实报告代码中被调用。一、Html类的定位与设计思想docs/html.rst是 Gramps 文档体系中针对gramps.plugins.lib.libhtml模块的 API 文档入口通过 Sphinx 的automodule/autoclass指令自动提取模块与类注释生成参考文档。其真正的主体是 gramps/plugins/lib/libhtml.py共 645 行中定义的Html类class Html(list): HTML class: Manages a rooted tree of HTML objects __slots__ [items, indent, inline, close, cms]Html类的核心设计思想可以概括为三点继承自list每个Html实例本身就是一个有序列表列表元素既可以是纯字符串文本、属性、注释等也可以是嵌套的Html实例从而天然构成一棵「根在列表头、子树为子元素」的 HTML 元素树。运算符重载模拟 DOM 操作通过重载、、-以及append/extend/replace等方法让「向某个标签内添加子节点」这一操作在语法层面与 HTML 结构保持一致。自带渲染与缩进控制write()方法按插入顺序做树遍历并逐行输出配合indent、inline、close三个开关可以精确控制每个标签的换行、缩进与闭合方式。模块顶部还通过__all__ [Html]明确了对外唯一公开的符号其他常量与辅助函数均为模块内部实现。二、构造函数三大开关与属性注入Html实例化时第一个位置参数是标签名其余位置参数会被插入到开标签与闭标签之间作为子内容def __init__(self, taghtml, *args, **keywargs):构造参数的核心语义如下参数取值含义tag字符串默认html要生成的 HTML 标签名若以开头则视为预格式化标签直接整体插入且不自动闭合closeNone*args0 或多个对象插入到开标签与闭标签之间的子元素/文本indentTrue/False/None默认TrueTrue表示相对父级缩进False表示不缩进None表示不缩进适用于pre等需要保留原样空白的内容inline布尔值默认FalseTrue时write()将该对象及所有子对象合并为单行字符串输出closeTrue/False/None默认TrueTrue正常闭合tag.../tagFalse自动闭合tag /None不提供闭合标签其余关键字参数任意除上述控制参数外全部转换为开标签上的keyvalue属性关键字参数的处理逻辑值得注意见 libhtml.pyindent、close、inline三个参数若取值为True/False/None会被直接设置为实例属性attr关键字用于一次性传入一段完整的原始属性字符串以_结尾的关键字如class_会被去掉尾下划线再作为属性名这是为了规避 Python 关键字冲突例如class必须写成class_php关键字用于注入一段 PHP 会话初始化代码放在开标签之前输出其余关键字如href、id、colspan全部原样拼入开标签。在 basepage.py 中可以看到真实用法示例trow Html(tr) ( Html(td, nbsp;, class_ColumnType, inlineTrue), ... ) tcell Html(td, class_ColumnValue Child, closeFalse, colspan2) with Html(table, class_infolist eventlist self.dir) as table2: thead Html(thead) header Html(tr)这里class_ColumnType正是通过尾下划线机制生成classColumnType属性closeFalse则把td渲染为自闭合标签。三、静态工厂方法从文档骨架到完整页面Html类提供了四个静态工厂方法用于快速搭建 HTML 文档骨架1.xmldecl(version, encoding, standalone)生成 XML 声明语句默认值为version1.0、encodingUTF-8、standalonenoHtml.xmldecl() # ?xml version1.0 encodingUTF-8 standaloneno?2.doctype(name, public, external_id)生成 DOCTYPE 声明。public默认external_id默认_HTML5空字符串。模块内预定义了全套 XHTML DTD 常量libhtml.py_XHTML10_STRICTXHTML 1.0 Strict_XTHML10_TRANSXHTML 1.0 Transitional_XHTML10_FRAMEXHTML 1.0 Frameset_XHTML11XHTML 1.1_XHTML10_BASIC/_XHTML11_BASICXHTML Basic_HTML5空字符串即 HTML5 文档类型3.html(xmlns, lang, php_session)生成根html对象。默认命名空间为http://www.w3.org/1999/xhtml_XMLNSlang默认en并同时生成xml:lang与lang两个属性Html.html() # html xmlnshttp://www.w3.org/1999/xhtml xml:langen langen4.head(title, encoding, html5)与page(...)head()生成head对象若传入title则自动加入titlehtml5True默认时用meta charset...声明字符集html5False时则生成http-equivcontent-type与Content-Style-Type两组传统 meta。page()是最高层的页面工厂一次返回(page, head, body)三个Html对象page, head, body Html.page(titleNone, encodingutf-8, langen, html5True, cmsFalse, php_sessionNone, ...)其内部逻辑是先生成html根对象若html5True追加 HTML5 DOCTYPE否则先addXML(encoding...)追加 XML 声明再addDOCTYPE(external_id_XHTML10_STRICT)追加 XHTML 1.0 Strict DOCTYPE生成headcmsFalse默认时生成bodycmsTrue时生成div classbody作为内容容器用于嵌入 CMS 页面通过page (head, body)把两个子节点挂到根上。四、树操作 API、、append与with上下文Html将元素树的所有增删操作都收敛到内部__add方法libhtml.py。其关键技巧是index len(self) - (1 if self.close else 0) self[index:index] value即始终在闭标签之前插入新内容——若标签需要闭合新子节点被插入到列表倒数第二个位置闭标签之前若标签自闭合则直接追加到末尾。这保证了树结构的物理布局永远是「开标签 → 子节点们 → 闭标签」。对外暴露的操作接口包括obj child/obj child追加单个元素字符串或Htmlobj (a, b, c)追加元组/列表形式的多个子节点append(value)、extend append追加语义与一致obj - child__isub__remove按值删除子节点replace(cur_value, value)就地替换子节点。更值得注意的是Html实现了上下文管理器协议def __enter__(self): return self def __exit__(self, exc_type, exc_val, exc_tb): return exc_type is None这使开发者可以直接用with语句维护嵌套结构这在 statistics.py 的概览页面代码中大量使用with Html(div, class_content, idsubsection narrative) as sec1: sec1 Html(h4, self._(Individuals), inlineTrue) sec1 Html(br, self._(Males) self.colon %d % males, inlineTrue) ...__exit__返回exc_type is None意味着异常不会被吞掉同时with块退出后区块变量仍可通过外部引用继续追加子节点非常灵活。五、输出机制write()的树遍历与缩进控制Html的输出核心是write()方法libhtml.pydef write(self, methodprint, indent\t, tabs): ... if self.indent is None: tabs elif self.indent: tabs indent if self.inline: method(str(%s%s % (tabs, self))) else: for item in self[:]: if isinstance(item, Html): item.write(methodmethod, indentindent, tabstabs) else: method(str(%s%s % (tabs, item)))其行为规则清晰可预测深度遍历遇到嵌套Html递归调用write()遇到字符串则逐行输出缩进indentTrue时每深入一层追加一个indent默认制表符\tindentNone如pre则清空缩进单行化inlineTrue的节点连同其全部子孙以__str__一次性输出为单行适合a、td、h4等行内元素。method参数默认为print可替换为任意可调用对象。在 basepage.py 的xhtml_writer中Gramps 正是把print绑定到已打开的输出文件htmlinstance.write(partial(print, fileoutput_file)) self.report.close_file(output_file, sio, date)而__str__的实现为%s * len(self) % tuple(self[:])即把列表中所有元素字符串与嵌套Html的字符串化结果顺序拼接。__iter__则提供插入顺序的树遍历生成器并把别名iterkeys/itervalues/iteritems都指向它兼容字典式遍历习惯。此外还有几个反射式属性均有 getter / setter / deletertag返回/修改当前标签名如把div改成span时开闭标签同步更新attr返回/设置开标签中的属性字符串inside返回开闭标签之间的子节点列表self[1:-1]可整体读取、赋值或清空。六、文档声明管理addXML与addDOCTYPE除了构造函数参数Html还支持在创建后动态追加文档级声明def addXML(self, version1.0, encodingUTF-8, standaloneno): self[0:0] [xmldecl] def addDOCTYPE(self, namehtml, publicPUBLIC, external_id_HTML5, *args): ... if self[0][:6] ?xml : self[1:1] [doctype] else: self[0:0] [doctype]addDOCTYPE的细节非常讲究DOCTYPE 声明必须跟在 XML 声明之后因此若列表头部已是?xml ...则插入到索引 1 的位置否则插入到最前。这一顺序保证了生成的文档通过 XML/XHTML 校验器。Html.page()正是利用这两个方法完成 XHTML 文档头装配的。在 basepage.py 的write_header中可以看到一个实用的兼容性处理当输出扩展名为.php或.cgi时会执行del page[0]删除 DOCTYPE 指令以避免 PHP 解析器报错——这说明page对象作为list元素级操作如del是开放可用的。七、配套模块HtmlBackend与libhtmlconst1.HtmlBackend文档后端适配层gramps/plugins/lib/libhtmlbackend.py 中的HtmlBackend继承自DocBackend是 Gramps 文档后端体系中的 HTML 实现。其 docstring 明确指出设计差异与其他后端不同我们不直接写文件而是写入一个Html对象在close()时才把整个页面写出。关键实现libhtmlbackend.pyopen()校验文件扩展名html/htm/php创建数据子目录并调用Html.page(langxml_lang(), titleself.title)初始化html_page、html_header、html_body三个对象write(obj)self.html_body obj把内容直接追加到body对象close()self.html_page.write(self.__write, indent )以两空格缩进将整棵文档树逐行写入文件STYLETAG_TO_PROPERTY/STYLETAG_MARKUP把文档格式标签映射为 CSS 属性或行内标签如BOLD→strongFONTCOLOR→color:%s;format_link(value)处理gramps://协议链接——当链接以gramps://开头时解析出对象类、属性与 handle通过build_link回调转换为真实页面 URL无法构建时退化为下划线文本。2.process_spaces预格式化文本的空格保真同一个模块中的process_spaces(intext, format)函数解决 HTML 渲染中空白折叠的经典问题当笔记文本为预格式化format 1时行首与连续的多个空格会被交替替换为普通空格与非断行空格nbsp;同时跳过 XML 标签内的内容format 0流式时文本原样保留。返回值为[处理后的文本, 有效字符数]。3.libhtmlconst字符集与版权声明常量gramps/plugins/lib/libhtmlconst.py 为报告配置提供两组常量_CHARACTER_SETS一组[显示名, 编码名]列表含 ISO-8859 系列、KOI8-R 等供网页报告编码下拉选项使用_CC与_COPY_OPTIONS7 种 Creative Commons 许可徽标的 HTML 片段与其对应菜单文案用于在页面页脚输出版权声明Standard copyright、各版本 CC-BY、以及 No copyright notice。这两组常量在 narrativeweb.py 中被显式导入支撑报告选项面板与页脚生成。八、在叙事网页报告中的实际调用链Html类是 gramps/plugins/webreport/ 下几乎所有页面模块的公共依赖addressbook.py、basepage.py、calendar.py、common.py、contact.py、download.py、event.py、family.py、heatmap.py、home.py、introduction.py、person.py、place.py、repository.py、source.py、statistics.py、surname.py等均以from gramps.plugins.lib.libhtml import Html方式导入。以 basepage.py 的write_header为例可以还原一条完整的页面装配链路从报告选项读取phpnotePHP 会话初始化笔记若扩展名为.php则从数据库取笔记内容确定xml:lang优先使用报告语言否则回退到xml_lang()该函数取当前 Gramps 语言代码前 5 位并将_替换为-如zh-CN调用Html.page(title, encoding, xmllang, cmsself.usecms, php_sessionnote, dirself.dir)得到页面骨架追加viewport、apple-mobile-web-app-capable、generator含 Gramps 程序名与版本号、author等 meta 标签若用户未开启internet_indexing选项还会追加robotsnoindex与googlebotnoindex由xhtml_writer通过htmlinstance.write(partial(print, fileoutput_file))最终落盘。另一类典型用法是动态 SVG 组件的生成——basepage.py 的create_toggle用Html(svg, viewBoxviewbox, class_triangle, ...)与Html(polygon, pointspoints)构建展开/收起按钮的三角形图标并通过Html(button, svg, idid_name, class_icon)把它包进按钮再挂到带onclick的h4上——这充分展示了Html类对属性、嵌套与行内/块级混排的完整表达能力。九、小结Html类在 Gramps 中的角色从 docs/html.rst 的 API 文档定义出发Html类是 Gramps 网页输出体系的基础设施文档层面它以list为物理存储、以标签树为逻辑结构用//with等 Python 原生语法表达 HTML 嵌套关系渲染层面indent/inline/close三开关配合write()深度遍历实现精确到每个标签的缩进与单行化控制文档类型层面通过预定义 XHTML/HTML5 DTD 常量与addXML/addDOCTYPE的顺序敏感插入保证输出文档的合法性生态层面它与HtmlBackend文档后端、process_spaces空格保真、libhtmlconst字符集与版权常量协同共同支撑 Gramps 叙事网页报告从数据到静态/动态站点的完整产出流程。对于希望理解 Gramps 网页生成原理、或需要构建类似「用 Python 生成结构化 HTML」工具的开发者而言libhtml.py 本身就是一个精炼且可直接借鉴的参考实现——它的树模型、运算符设计与缩进策略均值得逐行研读。赞分享桌面应用【免费下载链接】grampsSource code for Gramps Genealogical program项目地址https://gitcode.com/gh_mirrors/gr/gramps点击查看免费下载相关推荐I2L-MeshNet自定义数据集适配指南如何训练自己的3D人体模型I2L MeshNet自定义数据集适配指南如何训练自己的3D人体模型 想要使用I2L MeshNet训练自己的3D人体模型数据集吗这篇完整指南将带你一步步了colour-schemes的Template类HTML预览页生成模板引擎解析colour schemes的Template类HTML预览页生成模板引擎解析 Template类是colour schemes项目中负责HTML预览页生成的开发工具gstack /design-html 技能深度解析用 Pretext 原生文本布局引擎把设计稿生成生产级 HTMLgstack /design html 技能深度解析用 Pretext 原生文本布局引擎把设计稿生成生产级 HTML /design html 是 gstac人工智能AI 技能浏览器控制AI 评测上一篇从零到精通Smartparens 让 Emacs 括号操作如丝般顺滑下一篇CANN/asc-devkit: MatmulLeakyRelu融合算子高阶极限打磨创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考