Htmx.Net下载 - Htmx.Net源码下载

Htmx.Net

HTMX标志

这是一个旨在为HttpRequest和HttpResponse添加服务器端帮助器方法的包。这使得使用 htmx 服务器端概念变得更加简单。您还应该考虑阅读 Hyperscript，这是 HTMX 的一个可选配套项目。

如果您是 HTMX 新手，请查看有关 ASP.NET Core 开发人员的 HTMX 入门的本系列，其中还包括可能对您有用的示例项目和模式。

Htmx 扩展方法

入门

将Htmx NuGet 包安装到 ASP.NET Core 项目。

 dotnet add package Htmx

Http请求

使用HttpRequest ，我们可以确定请求是否是客户端上的 Htmx 发起的。

httpContext . Request . IsHtmx ( )

这可用于返回完整页面响应或部分页面呈现。

 // in a Razor Page
return Request . IsHtmx ( )
    ? Partial ( " _Form " , this )
    : Page ( ) ;

我们还可以检索 htmx 可能设置的其他标头值。

Request . IsHtmx ( out var values ) ;

在官方文档页面上阅读有关其他标头值的更多信息。

浏览器缓存

特别注意的是，请注意，如果您的服务器可以根据某些其他标头为同一 URL 呈现不同的内容，则需要使用 Vary 响应 HTTP 标头。例如，如果您的服务器在 Request.IsHtmx() 为 false 时呈现完整的 HTML，并且在 Request.IsHtmx() 为 true 时呈现该 HTML 的片段，则需要添加 Vary: HX-Request。这会导致缓存基于响应 URL 和 HX-Request 请求标头的组合进行键控，而不是仅基于响应 URL。

 // in a Razor Page
if ( Request . IsHtmx ( ) )
{
  Response . Headers . Add ( " Vary " , " HX-Request " ) ;
  return Partial ( " _Form " , this )
}

return Page ( ) ;

Http响应

我们可以使用Htmx扩展方法设置 Http Response 标头，该方法传递一个操作和HtmxResponseHeaders对象。

Response . Htmx ( h => {
    h . PushUrl ( " /new-url " )
     . WithTrigger ( " cool " )
} ) ;

在官方文档网站上阅读有关 HTTP 响应标头的更多信息。

触发客户端事件

您可以使用HX-Trigger标头通过 HTMX 触发客户端事件。 Htmx.Net 提供了一种WithTrigger辅助方法来配置您希望触发的一个或多个事件。

Response . Htmx ( h => {
    h . WithTrigger ( " yes " )
     . WithTrigger ( " cool " , timing : HtmxTriggerTiming . AfterSettle )
     . WithTrigger ( " neat " , new { valueForFrontEnd = 42 , status = " Done! " } , timing : HtmxTriggerTiming . AfterSwap ) ;
} ) ;

CORS 政策

默认情况下，所有 Htmx 请求和响应都将在跨源上下文中被阻止。

如果您在跨源上下文中配置应用程序，则在 ASP.NET Core 中设置 CORS 策略还允许您定义对请求和响应标头的特定限制，从而对可在 Web 之间交换的数据进行细粒度控制应用和不同的起源。

该库提供了一种向 CORS 策略公开 Htmx 标头的简单方法：

 var  MyAllowSpecificOrigins = " _myAllowSpecificOrigins " ;

var builder = WebApplication . CreateBuilder ( args ) ;

builder . Services . AddCors ( options =>
{
    options . AddPolicy ( name : MyAllowSpecificOrigins ,
                      policy  =>
                      {
                          policy . WithOrigins ( " http://example.com " , " http://www.contoso.com " )
                                   . WithHeaders ( HtmxRequestHeaders . Keys . All )  // Add htmx request headers
                                   . WithExposedHeaders ( HtmxResponseHeaders . Keys . All )  // Add htmx response headers
                      } ) ;
} ) ;

Htmx.TagHelpers

入门

将Htmx.TagHelpers NuGet 包安装到 ASP.NET Core 项目。面向 .NET Core 3.1+ 项目。

 dotnet add package Htmx.TagHelpers

通过将以下行添加到您的_ViewImports.cshtml中，使标记帮助程序在您的项目中可用：

 @addTagHelper *, Htmx.TagHelpers

您通常需要指向 ASP.NET Core 后端的 URL 路径。幸运的是， Htmx.TagHelpers模仿了 ASP.NET Core 中包含的 url 生成。这使得 HTMX 与 ASP.NET Core 应用程序的链接成为一种无缝体验。

 < div hx-target =" this " >
    < button hx-get
            hx-page =" Index "
            hx-page-handler =" Snippet "
            hx-swap =" outerHtml " >
        Click Me (Razor Page w/ Handler)
    </ button >
</ div >

< div hx-target =" this " >
    < button hx-get
            hx-controller =" Home "
            hx-action =" Index "
            hx-route-id =" 1 " >
        Click Me (Controller)
    </ button >
</ div >

< div hx-target =" this " >
    < button hx-post
            hx-route =" named " >
        Click Me (Named)
    </ button >
</ div >

Htmx配置

还包含一个额外的htmx-config标记帮助程序，可以将其应用于页面head的meta元素，从而使创建 HTMX 配置更加简单。例如，下面我们可以设置historyCacheSize 、默认indicatorClass ，以及是否包含ASP.NET Core的防伪令牌作为HTMX配置上的附加元素。

 <!DOCTYPE html >
< html lang =" en " >
< head >
    < meta name =" htmx-config " 
          historyCacheSize =" 20 "
          indicatorClass =" htmx-indicator "
          includeAspNetAntiforgeryToken =" true "
          />
    <!-- additional elements... -->
</ head >

生成的 HTML 将会是。

 <!DOCTYPE html >
< html lang =" en " >
< head >
    < meta name =" htmx-config " content =' {"indicatorClass":"htmx-indicator","historyCacheSize":20,"antiForgery":{"formFieldName":"__RequestVerificationToken","headerName":"RequestVerificationToken","requestToken":"<token>"}} ' />
    <!-- additional elements... -->
</ head >

HTMX 和防伪令牌

您可以在htmx-config元素上设置属性includeAspNetAntiforgerToken 。然后，您需要将这个额外的 JavaScript 包含在您的 Web 应用程序中。我们包含属性__htmx_antiforgery来跟踪已添加的事件侦听器。这可以防止我们意外地重新注册事件监听器。

 if ( ! document . body . attributes . __htmx_antiforgery ) {
    document . addEventListener ( "htmx:configRequest" , evt => {
        let httpVerb = evt . detail . verb . toUpperCase ( ) ;
        if ( httpVerb === 'GET' ) return ;
        let antiForgery = htmx . config . antiForgery ;
        if ( antiForgery ) {
            // already specified on form, short circuit
            if ( evt . detail . parameters [ antiForgery . formFieldName ] )
                return ;

            if ( antiForgery . headerName ) {
                evt . detail . headers [ antiForgery . headerName ]
                    = antiForgery . requestToken ;
            } else {
                evt . detail . parameters [ antiForgery . formFieldName ]
                    = antiForgery . requestToken ;
            }
        }
    } ) ;
    document . addEventListener ( "htmx:afterOnLoad" , evt => {
        if ( evt . detail . boosted ) {
            const parser = new DOMParser ( ) ;
            const html = parser . parseFromString ( evt . detail . xhr . responseText , 'text/html' ) ;
            const selector = 'meta[name=htmx-config]' ;
            const config = html . querySelector ( selector ) ;
            if ( config ) {
                const current = document . querySelector ( selector ) ;
                // only change the anti-forgery token
                const key = 'antiForgery' ;
                htmx . config [ key ] = JSON . parse ( config . attributes [ 'content' ] . value ) [ key ] ;
                // update DOM, probably not necessary, but for sanity's sake
                current . replaceWith ( config ) ;
            }
        }
    } ) ;
    document . body . attributes . __htmx_antiforgery = true ;
}

您可以通过两种方式访问该代码片段。第一种是在视图中使用HtmxSnippet静态类。

 <script>
@Html.Raw(HtmxSnippets.AntiforgeryJavaScript)
</script>

一种更简单的方法是使用扩展IHtmlHelper的HtmlExtensions类。

 @Html.HtmxAntiforgeryScript()

此 html 帮助程序将生成一个<script>标记以及前面提到的 JavaScript。注意：您仍然可以为htmx:configRequest注册多个事件处理程序，因此拥有多个事件处理程序是可以的。

请注意，如果hx-[get|post|put]属性位于<form ..>标记上，并且<form>元素具有method="post" （以及空或缺失的action="" ）属性， ASP.NET 标记帮助程序将添加防伪令牌作为input元素，您无需像上面那样进一步配置您的请求。您还可以使用hx-include指向表单，但这一切都取决于偏好问题。

此外，推荐的方法是使用HtmxAntiforgeryScriptEndpoint ，它可以让您将 JavaScript 文件映射到特定端点，默认情况下它将是_htmx/antiforgery.js 。

app . UseAuthorization ( ) ;
// registered here
app . MapHtmxAntiforgeryScript ( ) ;
app . MapRazorPages ( ) ;
app . MapControllers ( ) ;

您现在可以使用缓存、身份验证等配置此端点。更重要的是，您现在可以通过应用defer标记在head标记中使用脚本，这比在body元素末尾使用 JavaScript 更好。

 < head >
    < meta charset =" utf-8 "/>
    < meta name =" viewport " content =" width=device-width, initial-scale=1.0 "/>
    < meta
        name =" htmx-config "
        historyCacheSize =" 20 "
        indicatorClass =" htmx-indicator "
        includeAspNetAntiforgeryToken =" true "/>
    < title > @ViewData["Title"] - Htmx.Sample </ title >
    < link rel =" stylesheet " href =" ~/lib/bootstrap/dist/css/bootstrap.min.css "/>
    < link rel =" stylesheet " href =" ~/css/site.css " asp-append-version =" true "/>
    < script src =" ~/lib/jquery/dist/jquery.min.js " defer > </ script >
    < script src =" ~/lib/bootstrap/dist/js/bootstrap.bundle.min.js " defer > </ script >
    < script src =" https://unpkg.com/htmx.org@@1.9.2 " defer > </ script >
    <!-- this uses the static value in a script tag -->
    < script src =" @HtmxAntiforgeryScriptEndpoints.Path " defer > </ script >
</ head >