Kobweb版本更新及使用场景记录

前言

本文主要记录Kobweb的一些重要更新记录，如需了解历史版本的更新记录请查看:Kobweb Release List

V0.20.4

Tip

原文链接: https://github.com/varabyte/kobweb/releases/tag/v0.20.4

本次发布包含了多个杂项修复。

较为有趣的新功能之一是，现在你可以选择在构建时自动将 <head> 块中声明的外部资源链接转换为本地托管文件。

这允许用户使用类似 Silk 的 Font Awesome 图标等功能，或在构建脚本中添加指向外部 URL 的链接（例如字体、脚本或样式表），然后让 Kobweb 自动下载并本地托管。

Important

计划升级？请查看README中的升级说明。

更新内容

`前端`

修复了由于舍入可能导致的SVG图标裁剪问题。
现在允许创建没有根路由("/")的站点。
- 这在之前本应是一个警告，但在某次重构中变成了错误。
当在当前站点域名上调用 navigateTo 时，现在表现为混合内部/外部路由。
- 例如：使用 navigateTo("https://yoursite.com/about") 而不是简单的 navigateTo("/about")
  - 作为外部路由，它基本上会向服务器发出新的获取请求（而内部导航完全在客户端进行）。
作为内部路由，它使用"打开内部链接"策略，在当前页面打开目标页面而不是新标签页。
- 如果你为站点配置了基本路径，在这种情况下将不会应用。
修复了切换标签页后工具提示可能重新打开的问题。
- 结果似乎可能依赖于浏览器/操作系统，我们将在下一个版本继续调查这个问题。

`Silk`

为提示框添加了新的 OutlinedFilledCalloutVariant。
- 这给提示框一个实心填充色外观和细边框。

后端

在开发模式下禁用CSS文件缓存，修复了实时重载问题。
- 这会影响那些在 resources/public 文件夹中托管原始CSS文件并在开发过程中编辑它们的用户。
为 Request 和 Response 类添加了有用的、支持kotlinx序列化的辅助方法。
- 即 request.readBody<SomeValue>() 和 response.setBody<SomeValue>(someValue)。
服务器现在会记录任何声明的CORS配置，这在调试CORS问题时很有帮助。
- 我们添加这个是因为有用户在 .kobweb/conf.yaml 中放入了CORS值，但缩进不正确，导致服务器找不到它们，而用户并不知道。

Gradle

添加了对拦截 <head> 元素中URL的构建脚本支持，特别适用于将CDN转换为自托管资源。
- 详见说明部分。
添加了新的kobwebSiteRoutes扩展属性，允许你查询站点中声明的所有路由。
- 详见说明部分。
修复了当你在站点目录外运行原始Gradle kobwebStart -t命令时实时重载会中断的问题。

Markdown

现在可以在提示框内指定替代的提示框变体

> [!NOTE {variant = com.varabyte.kobweb.silk.components.display.OutlinedCalloutVariant}]
> Lorem ipsum dolor sit amet, consectetur adipiscing elit.

更多关于Markdown中提示框的信息，请参见README。

说明

URL拦截和自托管

kobweb {
    app {
        index {
            interceptUrls {
                enableSelfHosting()
            }
        }
    }
}

许多网站通过内容分发网络（CDN）链接来引用外部资源，这是一种便捷的解决方案。许多Web资源的安装说明通常都建议使用这种方式。

不幸的是，这种简单的解决方案可能导致网站不符合GDPR规范。

Note

关于GDPR的进一步讨论超出了这些发布说明的范围，但如果你感兴趣，可以查看https://en.wikipedia.org/wiki/Content_delivery_network#Security_and_privacy等链接，并找到讨论这个话题的博客文章。

处理GDPR合规性的常见方法是自己托管资源。然而，没有一种通用的解决方案。

Kobweb希望让用户选择最适合其需求的解决方案，因此在这个版本中，我们通过提供对 <head> 元素中URL的拦截支持，找到了一种支持两种方式的简单方法。

你可以通过 interceptUrls 块添加URL拦截规则。本质上，如果你的head元素引用了外部链接，你可以使用URL拦截来检测它们并用新值替换，通常是你自己服务器上的本地路径。

Note

这些链接可能来自你添加为依赖项的Kobweb库 - 例如，Kotlin Bootstrap library添加了一些自己的链接。

如果你在 interceptUrls 块中调用 enableSelfHosting()，Kobweb会为你完成所有这些工作。

例如，kobweb create examples/opengl 项目在其构建脚本中有以下代码：

kobweb {
    app {
        index {
            head.add {
                script {
                    src = "https://cdnjs.cloudflare.com/ajax/libs/gl-matrix/3.4.2/gl-matrix-min.js"
                }
            }
        }
    }
}

如果你在 index 块中添加 interceptUrls { enableSelfHosting() }，那么当你运行并打开项目时，你会看到 gl-matrix-min.js 的副本被本地下载。如果你在开发工具的网络标签中检查站点，查看 gl-matrix-min.js 的托管位置，你会看到类似：http://yoursite.com/_kobweb/self-host/cdnjs.cloudflare.com/ajax/libs/gl-matrix/3.4.2/gl-matrix-min.js

如果你想要更多手动控制，interceptUrls 块也提供了 replace 方法：

interceptUrls {
   replace("https://cdnjs.cloudflare.com/ajax/libs/gl-matrix/3.4.2/gl-matrix-min.js", "/gl-matrix/script.js")
}

这时，你需要自己负责将 /src/jsMain/resources/public/gl-matrix/script.js 添加到你的项目中。

总的来说，CDN链接提供了很多优势，所以你不应该仅仅因为容易就替换它们 - 这会增加你的带宽账单，而且你提供这些文件的速度可能比CDN慢得多。但至少现在Kobweb可以支持决定进行这种更改的项目。

`kobwebSiteRoutes`

在Kobweb构建脚本中查询注册的站点路由列表可能很有用，例如让你以编程方式创建站点地图。

在自定义任务中使用 kobwebSiteRoutes 看起来像这样：

tasks.register("createSitemap") {
     // 在配置阶段获取
     val routesProvider: Provider<List<String>> = kobwebSiteRoutes 
     inputs.property("routes", routesProvider)
     doLast {
         val routes = routesProvider.get() // 在执行阶段查询
         val sitemapStr = buildList {
             routes.forEach { route -> add("https://yoursite.com$route") }
         }.joinToString("\n")
         // 将sitemapStr保存到磁盘...
     }
 }

Important

注意在上面的例子中，kobwebSiteRoutes 属性在任务配置阶段被查询，然后其返回值在任务执行阶段被查询。如果你不这样做，Gradle可能会因为违反缓存要求而报错。

完整更新日志：v0.20.3...v0.20.4