swift-html

swift-html

Swift实现的类型安全HTML文档生成库

swift-html是一个Swift库,用于创建类型安全的HTML文档。它将HTML直接嵌入Swift的类型系统,防止运行时错误和无效HTML。该库提供树状结构创建文档,支持文档转换,并增强安全性。可与Vapor等Swift web框架集成,是模板语言的有力替代。

SwiftHTMLDSL类型安全可扩展Github开源项目

🗺 swift-html

CI

一个用于创建类型安全、可扩展和可转换的HTML文档的Swift DSL。

目录

动机

目前在Swift中渲染HTML的流行选择是使用模板语言,但它们会使您的应用程序暴露于运行时错误无效HTML的风险。我们的库通过将HTML直接嵌入到Swift强大的类型系统中,在编译时防止这些运行时问题。

示例

可以以树状方式创建HTML文档,类似于创建嵌套的JSON文档:

import Html let document: Node = .document( .html( .body( .h1("欢迎!"), .p("你找到了我们的网站!") ) ) )

在底层,这些标签函数htmlbodyh1等只是创建和嵌套Node类型的实例,它是一个简单的Swift枚举。由于Node只是一个简单的Swift类型,我们可以以各种有趣的方式对其进行转换。举个简单的例子,如果我们想从文档中删除所有感叹号实例,该怎么办?

func unexclaim(_ node: Node) -> Node { switch node { case .comment: // 不需要转换HTML注释 return node case .doctype: // 不需要转换文档类型 return node case let .element(tag, attrs, children): // 递归转换元素的所有子元素 return .element(tag, attrs, unexclaim(children)) case let .fragment(children): // 递归转换片段的所有子元素 return .fragment(children.map(unexclaim)) case let .raw(string): // 通过将感叹号替换为句号来转换文本节点 return .raw(string.replacingOccurrences(of: "!", with: ".")) case let .text(string): // 通过将感叹号替换为句号来转换文本节点 return .text(string.replacingOccurrences(of: "!", with: ".")) } } unexclaim(document)

创建文档后,您可以使用render函数渲染它:

render(document) // <!doctype html><html><body><h1>欢迎!</h1><p>你找到了我们的网站!</p></body></html>

当然,您也可以先通过unexclaim转换运行文档,然后再渲染它:

render(unexclaim(document)) // <!doctype html><html><body><h1>欢迎.</h1><p>你找到了我们的网站.</p></body></html>

现在文档变得非常严肃认真了😂。

安全性

由于我们将DSL嵌入Swift中,我们可以利用一些高级Swift功能,在构建HTML文档时添加额外的安全层。一个简单的例子是,我们可以加强许多HTML API,强制使用它们的真实类型,而不仅仅依赖于字符串。

let imgTag = Node.img(attributes: [.src("cat.jpg"), .width(400), .height(300)]) render(imgTag) // <img src="https://raw.githubusercontent.com/pointfreeco/swift-html/main/cat.jpg" width="400" height="300">

这里src属性接受一个字符串,但widthheight接受整数,因为在这些属性中放入其他任何内容都是无效的。

一个更高级的例子是,<li>标签只能放在<ol><ul>标签内,我们可以表示这一事实,使得构建无效文档变得不可能:

let listTag = Node.ul( .li("猫"), .li("狗"), .li("兔子") ) // ✅ 编译通过! render(listTag) // <ul><li>猫</li><li>狗</li><li>兔子</li></ul> Node.div( .li("猫"), .li("狗"), .li("兔子") ) // 🛑 编译错误

设计

该库的核心是一个包含6个情况的枚举:

public enum Node { case comment(String) case doctype(String) indirect case element(String, [(key: String, value: String?)], Node) indirect case fragment([Node]) case raw(String) case text(String) }

这个类型允许您表达可能存在的每一个HTML文档。然而,直接使用这个类型可能有点笨拙,所以我们提供了一堆辅助函数,以类型安全的方式构造整个HTML规范中的每个元素和属性:

// 不使用辅助函数 Node.element("html", [], [ .element("body", [], [ .element("p", [], [.text("你找到了我们的网站!")]) ]) ]) // 相比之下 // 使用辅助函数 Node.html( .body( .h1("欢迎!"), .p("你找到了我们的网站!") ) )

这使得HTML文档的"Swift化"看起来非常类似于原始文档。

常见问题

我可以将此库与现有的Swift Web框架(如Kitura和Vapor)一起使用吗?

可以!我们甚至提供了插件库,减少了将此库与Kitura和Vapor一起使用的摩擦。在以下仓库中可以找到更多信息:

为什么我要使用这个而不是模板语言?

模板语言很流行且易于上手,但它们有许多缺点:

  1. 字符串API:模板语言总是强类型的,因为您将模板作为一个大字符串提供,然后在运行时插值值并执行逻辑。这意味着我们在Swift中认为理所当然的事情,比如编译器捕获拼写错误和类型不匹配,在运行代码之前都不会被注意到。

  2. 不完整的语言:模板语言就是编程语言。这意味着您应该期望这些语言具备其他成熟语言(如Swift)所具有的所有优点。这包括语法高亮、IDE自动完成、静态分析、重构工具、断点、调试器,以及使Swift强大的一系列功能,如let绑定、条件语句、循环等。然而,现实是没有一种模板语言支持所有这些功能。

  3. 僵化:模板语言是僵化的,因为它们不允许我们习惯在Swift中对数据结构执行的那些组合和转换。无法简洁地遍历您构建的文档,并检查或转换您访问的节点。这种能力有许多应用,例如能够美化打印或最小化HTML输出,或编写一个转换,允许您将CSS样式表内联到HTML节点中。由于模板语言的工作方式,有很多可能性对您来说是完全封闭的。

这个库中的DSL解决了所有这些问题,并打开了对模板语言完全封闭的大门。

什么时候使用模板语言比swift-html更合适?

有几个原因可能让您仍然想使用模板语言:

  1. 设计师向您提供了一个大型HTML文档,您只想进行一些值插值或逻辑。在这种情况下,您可以简单地将该HTML复制并粘贴到模板中,添加一些插值标记,您就可以从Web应用程序提供完整的页面了。

  2. 您需要渲染非HTML文档。模板语言的美妙之处在于它直接输出纯文本,因此可以模拟任何类型的文档,无论是HTML、markdown、XML、RSS、ATOM、LaTeX等。

  3. 在单个表达式中创建_非常_大的文档可能会导致编译时间增加,而模板不会被Swift编译,因此不会影响编译时间。幸运的是,这通常不是问题,因为很容易将文档分解成任意多个小部分,从长远来看,这可能会导致更可重用的代码。

如果您确实决定模板语言更适合您的需求,那么您应该考虑HypertextLiteral,它以更安全的方式提供类似模板的功能。

安装

您可以通过将swift-html作为包依赖项添加到Xcode项目中。

https://github.com/pointfreeco/swift-html

如果您想在SwiftPM项目中使用swift-html,只需在Package.swift中的dependencies子句中添加它即可:

dependencies: [ .package(url: "https://github.com/pointfreeco/swift-html", from: "0.4.0") ]

想了解更多?

这些概念(以及更多)在Point-Free的一系列视频中得到了深入探讨,这是一个由Brandon WilliamsStephen Celis主持的探索函数式编程和Swift的视频系列。

这个库的想法在以下几集中被探讨:

<a href="https://www.pointfree.co/episodes/ep26-domain-specific-languages-part-1"> <img alt="视频海报图片" src="https://d1hf1soyumxcgv.cloudfront.net/0026-dsl-pt1/poster.jpg" width="480"> </a>

许可证

所有模块都在MIT许可证下发布。有关详细信息,请参阅LICENSE

编辑推荐精选

讯飞星火

讯飞星火

深度推理能力全新升级,全面对标OpenAI o1

科大讯飞的星火大模型,支持语言理解、知识问答和文本创作等多功能,适用于多种文件和业务场景,提升办公和日常生活的效率。讯飞星火是一个提供丰富智能服务的平台,涵盖科技资讯、图像创作、写作辅助、编程解答、科研文献解读等功能,能为不同需求的用户提供便捷高效的帮助,助力用户轻松获取信息、解决问题,满足多样化使用场景。

热门AI开发模型训练AI工具讯飞星火大模型智能问答内容创作多语种支持智慧生活
Spark-TTS

Spark-TTS

一种基于大语言模型的高效单流解耦语音令牌文本到语音合成模型

Spark-TTS 是一个基于 PyTorch 的开源文本到语音合成项目,由多个知名机构联合参与。该项目提供了高效的 LLM(大语言模型)驱动的语音合成方案,支持语音克隆和语音创建功能,可通过命令行界面(CLI)和 Web UI 两种方式使用。用户可以根据需求调整语音的性别、音高、速度等参数,生成高质量的语音。该项目适用于多种场景,如有声读物制作、智能语音助手开发等。

Trae

Trae

字节跳动发布的AI编程神器IDE

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

AI工具TraeAI IDE协作生产力转型热门
咔片PPT

咔片PPT

AI助力,做PPT更简单!

咔片是一款轻量化在线演示设计工具,借助 AI 技术,实现从内容生成到智能设计的一站式 PPT 制作服务。支持多种文档格式导入生成 PPT,提供海量模板、智能美化、素材替换等功能,适用于销售、教师、学生等各类人群,能高效制作出高品质 PPT,满足不同场景演示需求。

讯飞绘文

讯飞绘文

选题、配图、成文,一站式创作,让内容运营更高效

讯飞绘文,一个AI集成平台,支持写作、选题、配图、排版和发布。高效生成适用于各类媒体的定制内容,加速品牌传播,提升内容营销效果。

热门AI辅助写作AI工具讯飞绘文内容运营AI创作个性化文章多平台分发AI助手
材料星

材料星

专业的AI公文写作平台,公文写作神器

AI 材料星,专业的 AI 公文写作辅助平台,为体制内工作人员提供高效的公文写作解决方案。拥有海量公文文库、9 大核心 AI 功能,支持 30 + 文稿类型生成,助力快速完成领导讲话、工作总结、述职报告等材料,提升办公效率,是体制打工人的得力写作神器。

openai-agents-python

openai-agents-python

OpenAI Agents SDK,助力开发者便捷使用 OpenAI 相关功能。

openai-agents-python 是 OpenAI 推出的一款强大 Python SDK,它为开发者提供了与 OpenAI 模型交互的高效工具,支持工具调用、结果处理、追踪等功能,涵盖多种应用场景,如研究助手、财务研究等,能显著提升开发效率,让开发者更轻松地利用 OpenAI 的技术优势。

Hunyuan3D-2

Hunyuan3D-2

高分辨率纹理 3D 资产生成

Hunyuan3D-2 是腾讯开发的用于 3D 资产生成的强大工具,支持从文本描述、单张图片或多视角图片生成 3D 模型,具备快速形状生成能力,可生成带纹理的高质量 3D 模型,适用于多个领域,为 3D 创作提供了高效解决方案。

3FS

3FS

一个具备存储、管理和客户端操作等多种功能的分布式文件系统相关项目。

3FS 是一个功能强大的分布式文件系统项目,涵盖了存储引擎、元数据管理、客户端工具等多个模块。它支持多种文件操作,如创建文件和目录、设置布局等,同时具备高效的事件循环、节点选择和协程池管理等特性。适用于需要大规模数据存储和管理的场景,能够提高系统的性能和可靠性,是分布式存储领域的优质解决方案。

TRELLIS

TRELLIS

用于可扩展和多功能 3D 生成的结构化 3D 潜在表示

TRELLIS 是一个专注于 3D 生成的项目,它利用结构化 3D 潜在表示技术,实现了可扩展且多功能的 3D 生成。项目提供了多种 3D 生成的方法和工具,包括文本到 3D、图像到 3D 等,并且支持多种输出格式,如 3D 高斯、辐射场和网格等。通过 TRELLIS,用户可以根据文本描述或图像输入快速生成高质量的 3D 资产,适用于游戏开发、动画制作、虚拟现实等多个领域。

下拉加载更多