Blazor集成DataTables首次加载报错：$(...).DataTable is not a function

问题描述 #

开发Blazor应用时使用DataTables展示表格，首次进入页面时出现TypeError: $(...).DataTable is not a function错误；刷新页面（F5/刷新按钮）后错误消失，DataTables能正常显示。

原因分析 #

核心问题是脚本加载顺序错误：

• 自定义的DataTables调用脚本（MyEnduranceHubDataTables.js）在DataTables官方核心脚本之前加载，当Blazor首次执行DataTables.init时，DataTables还未挂载到jQuery对象上，导致找不到DataTable方法。
• 刷新页面时，浏览器缓存使得脚本加载顺序的实际执行时机变化，或者Blazor渲染流程的细微差异，让DataTables脚本提前完成加载，因此偶然正常。

解决方案 #

1. 调整_layout.cshtml中的脚本加载顺序 #

将DataTables相关脚本移到自定义脚本之前，确保依赖先加载。修改后的顺序如下：

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.1/jquery.min.js"></script>
<!-- 先加载DataTables核心脚本 -->
<script src="https://cdn.datatables.net/1.12.1/js/jquery.dataTables.min.js"></script>
<script src="https://cdn.datatables.net/1.12.0/js/dataTables.bootstrap5.min.js"></script>
<!--Charts-->
<script src="vendor/apexcharts.min.js"></script>
<script src="vendor/chart.min.js"></script>
<!--Dashboard duration calendar-->
<script src="vendor/moment.min.js"></script>
<script src="vendor/daterangepicker.js"></script>
<script src="https://cdn.jsdelivr.net/npm/fullcalendar@5.9.0/main.min.js"></script>
<!-- 自定义脚本放在依赖之后 -->
<script src="/js/MyEnduranceHubFullCalendar.js"></script>
<script src="/js/MyEnduranceHubDataTables.js"></script>
<!-- Blazor脚本放在最后 -->
<script src="_framework/blazor.server.js"></script>

2. 优化Blazor页面中的调用逻辑 #

避免每次OnAfterRenderAsync都初始化DataTables，只在首次渲染时执行：

[Inject] private IJSRuntime JSRuntime { get; set; }
private List<VmTeam> teams = null!;

protected override void OnInitialized()
{
    teams = new()
    {
        new VmTeam() { Id = 1, Name = "PCDC BLUE", CreatedBy = 1 },
        new VmTeam() { Id = 1, Name = "PCDC RED", CreatedBy = 1 },
        new VmTeam() { Id = 1, Name = "PCDC YELLOW", CreatedBy = 1 },
        new VmTeam() { Id = 1, Name = "PCDC GREEN", CreatedBy = 1 }
    };
    base.OnInitialized();
}

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    // 仅在首次渲染时初始化DataTables
    if (firstRender)
    {
        var columns = typeof(VmTeam).GetProperties().Select(p => p.Name.ToLower());
        await JSRuntime.InvokeVoidAsync("DataTables.init", "datatable", columns, teams, DotNetObjectReference.Create(this));
    }
    await base.OnAfterRenderAsync(firstRender);
}

3. 优化JS初始化代码 #

移除多余的$(document).ready，因为Blazor的OnAfterRenderAsync已经确保DOM元素存在：

DataTables = (() => {
return {
    //main function to initiate the module
    init: function (Id, datacolumns, values, dotNetReference) {
        $('#' + Id).DataTable({
            data: values,
            columns: [
                { data: 'id' },
                { data: 'name' },
                { data: 'createdBy' }
            ]
        });
    }
};
})();

验证说明 #

调整后首次进入页面时，DataTables脚本已提前加载完成，Blazor首次渲染时调用DataTables.init就能找到对应的jQuery方法，不会再出现报错；同时避免重复初始化，保证表格正常渲染。

内容的提问来源于stack exchange，提问作者Diceble