Marvin's Blog【程式人生】

Ability will never catch up with the demand for it

15 Aug 2021

Blazor文档阅读【八】

Blazor 》 JS Interop。

Blazor JavaScript interoperability (JS interop)

Interaction with the Document Object Model (DOM)

只有对于不与Blazor交互的标的,才用JS来变更DOM。Blazor内部维护DOM的镜像,如果DOM在Blazor以外被修改,会导致状态不一致。

Location of JavaScipt

可以用以下方式加载JS代码:

  • 通过<head>标签,不推荐
  • 通过<body>标签
  • 通过加载外部的JS文件
  • 在Blazor启动后注入脚本

不要在Blazor组件中使用<script>标签

Load a script in markup

示例:

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

不推荐的理由:

  • JS interop可能会失败,如果它来与Blazor的话
  • 提高页面的交互延迟

Load a script in markup

示例:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

Load a script from an external JS file (.js)

示例:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

若JS文件由组件库提供,则:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js"></script>
    <script src="./_content/{LIBRARY NAME}/{SCRIPT PATH AND FILENAME (.js)}"></script>
</body>

Inject a script after Blazor starts

要将autostart设置成false。然后在head标签中导入目标文件,然后:

<body>
    ...

    <script src="_framework/blazor.{webassembly|server}.js" 
        autostart="false"></script>
    <script>
      Blazor.start().then(function () {
        var customScript = document.createElement('script');
        customScript.setAttribute('src', 'scripts.js');
        document.head.appendChild(customScript);
      });
    </script>
</body>

JavaScript isolation in JavaScript modules

推荐使用JS modules:

好处:

  • 导入的JS不影响全局名字空间
  • 不要求组件或者组件库的消费者导入相关的JS

Call JavaScript functions from .NET methods in ASP.NET Core Blazor

需要注入IJSRuntime,并调用以下方法之一:

  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync

下面是注意点:

  • 需要调用的函数标识符用字符串表示,并且仅限于范围(即window)。若要调用window.someScope.someFunction,标识符为someScope.someFunction。调用前不需要注册。
  • Object[]的形式传入任意的可序列化为JSON的实参
  • CancellationToken记号用来传播操作需要被取消的通知
  • TimeSpan代表JS操作的时限
  • 返回值TValue必须可序列化为JSON
  • InvokeAsync返回的是JS的Promise,需要拆掉Promise的包装来获取其所等待的值

对于Server,预渲染的时候发生在服务端,因而无法调用JS。

文中举了一个调用https://developer.mozilla.org/docs/Web/API/TextDecoder的例子。

Invoke JavaScript functions without reading a returned value

使用InvokeVoidAsync的场景:

下面是一个示例函数:

<script>
  window.displayTickerAlert1 = (symbol, price) => {
    alert(`${symbol}: $${price}!`);
  };
</script>

Invoke JavaScript functions and read a returned value (InvokeAsync)

InvokeAsync则用在需要读取JS调用的值的场景。

目标函数示例:

<script>
  window.displayTickerAlert2 = (symbol, price) => {
    if (price < 20) {
      alert(`${symbol}: $${price}!`);
      return "User alerted in the browser.";
    } else {
      return "User NOT alerted.";
    }
  };
</script>

Dynamic content generation scenarios

如果需要在BuildRenderTree的时候动态生成内容,那么需要:

[Inject]
IJSRuntime JS { get; set; }

Detect when a Blazor Server app is prerendering

略。

Location of JavaScipt

似乎重复了。

JavaScript isolation in JavaScript modules

假设有这么一个JS module:

wwwroot/scripts.js

export function showPrompt(message) {
  return prompt(message, 'Type anything here');
}

然后使用InvokeAsync导入:

            module = await JS.InvokeAsync<IJSObjectReference>("import", 
                "./scripts.js");

导入的标的类型是 IJSObjectReference。可以在此标的上调用JS的方法:

        return await module.InvokeAsync<string>("showPrompt", message);

用完之后需要释放:

            await module.DisposeAsync();

IJSInProcessObjectReference则表示到一个JS标的的引用,其上的函数可以以同步的方式调用。

Capture references to elements

一些JS互操作场景需要到HTML元素的引用,比如一个UI库需要请求一个元素的引用用于初始化,或需要调用元素提供的命令式的API,比如click以及play。

组件中,以如下方式获取HTML元素的引用:

  • 在生成HTML元素时指定@ref属性
  • 定义一个类型为ElementReference的字段,用于匹配@ref的值

下面是一个例子:

<input @ref="username" ... />

@code {
    private ElementReference username;
}

不要变更本由Blazor管理的内容

ElementReference会通过JS interop传给JS代码,后者接收到的是一个HTMLElement现例,可用于普通的DOM API。

下面例子中定义了一个.NET的扩展方法TriggerClickEvent可以发送一个鼠标点击事件给元素:

window.interopFunctions = {
  clickElement : function (element) {
    element.click();
  }
}

下面是使用示例:

@inject IJSRuntime JS

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await JS.InvokeVoidAsync(
            "interopFunctions.clickElement", exampleButton);
    }
}

也可以在TriggerClickEvent上加一个额外参数:

public static async Task TriggerClickEvent(this ElementReference elementRef, 
    IJSRuntime js)
{
    await js.InvokeVoidAsync("interopFunctions.clickElement", elementRef);
}

下面的代码假设TriggerClickEvent方法存在于JsInteropClasses:

@inject IJSRuntime JS
@using JsInteropClasses

<button @ref="exampleButton">Example Button</button>

<button @onclick="TriggerClick">
    Trigger click event on <code>Example Button</code>
</button>

@code {
    private ElementReference exampleButton;

    public async Task TriggerClick()
    {
        await exampleButton.TriggerClickEvent(JS);
    }
}

到元素的引用在组件渲染之后才有效,如果需要对其进行操作,需要等到OnAfterRender*

对于泛型,返回的是ValueTask<TResult>

public static ValueTask<T> GenericMethod<T>(this ElementReference elementRef, 
    IJSRuntime js)
{
    return js.InvokeAsync<T>("{JAVASCRIPT FUNCTION}", elementRef);
}

下面的代码假设GenericMethod 来自JsInteropClasses。

Reference elements across components

ElementReference不能在组件间传递,因为:

  • 元素现例只有在组件渲染时才可能存在
  • ElementReference是struct,无法作为组件参数

上级组件可以获取元素引用,然后:

  • 允许子组件注册回调
  • 在OnAfterRender对传入的元素引用执行注册的回调

例子有点复杂,略。

Harden JavaScript interop calls

主要用于Server应用。WASM应用或也可以设置一个时限。

Avoid circular object references

具有回环引用的标的无法序列化,无法用于:

  • .NET方法调用
  • 从C#调用JS,但是返回结果具有回环引用

JavaScript libraries that render UI

可以让UI组件返回空元素给Blazor,让Blazor以为里面内有内容,就不执行diff。

文中给了一个地图的例子。

Size limits on JavaScript interop calls

主要限制于Sever应用。

Unmarshalled JavaScript interop

使用IJSUnmarshalledObjectReference可以以非序列化的方式引用JS标的。

值得多研究研究。

Catch JavaScript exceptions

在.NET中,JS的异常以JsException形式存在。

Additional resources

代码示例:https://github.com/dotnet/AspNetCore/blob/main/src/Components/test/testassets/BasicTestApp/InteropComponent.razor。(主分支上的示例对标最新的.NET版本。若要其他版本,需要切换分支标签)

Call .NET methods from JavaScript functions in ASP.NET Core Blazor

Invoke a static .NET method

对应的方法:

  • DotNet.invokeMethod,返回结果
  • DotNet.invokeMethodAsync,返回JS Promise

能被调用的.NET方法必须是public,static以及标注为[JSInvokable],示例:

@code {
    [JSInvokable]
    public static Task{<T>} {.NET METHOD ID}()
    {
        ...
    }
}

可以指定别名:

[JSInvokable("DifferentMethodName")]

C#中的异步操作,可以参考https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/

Invoke an instance .NET method

  • 需要将.NET现例的引用包裹在DotNetObjectReference里面传给JS,要调用其Create方法
  • 在传入的引用上调用invokeMethod或者invokeMethodAsync
  • 使用完毕的时候,舍弃引用

例如:

DotNet.invokeMethodAsync('{ASSEMBLY NAME}', '{.NET METHOD ID}', {ARGUMENTS});

Component instance examples

例子略

Class instance examples

例子略

Component instance .NET method helper class

助手类可以将.NET现例的方法作为Action调用,适用于以下场景:

  • 同类型的不同组件在当前页面渲染
  • 对于Server应用,多用户并发使用同一组件

例子略。

Location of JavaScipt

似乎是重复内容

Avoid circular object references

似乎是重复内容

Size limits on JavaScript interop calls

似乎是重复内容

JavaScript isolation in JavaScript modules

似乎是重复内容

(本篇完)

Categories