自定义场景对象中的变量

变量为交互式仪表板奠定了基础。它们允许动态配置要查询的数据。

除了标准变量支持之外，Scenes 还提供了一个 API，使自定义场景对象能够与变量一起使用。此 API 为仪表板创建者提供了更多可能性。

在自定义场景对象中使用变量

请按照以下步骤使自定义场景对象对变量做出反应。

步骤 1. 构建自定义场景对象

首先构建一个将显示提供文本的自定义场景对象。

此对象将

具有一个简单的状态，其中包含一个字符串值（text 属性）。
渲染一个textarea 用于状态修改，以及一个预格式化的文本块用于显示text 状态的当前值。

import { SceneObjectState, SceneObjectBase, SceneComponentProps } from '@grafana/scenes';
import { TextArea } from '@grafana/ui';

interface TextInterpolatorState extends SceneObjectState {
  text: string;
}

class TextInterpolator extends SceneObjectBase<TextInterpolatorState> {
  static Component = TextInterpolatorRenderer;

  constructor(text: string) {
    super({ text });
  }

  onTextChange = (text: string) => {
    this.setState({ text });
  };
}

function TextInterpolatorRenderer({ model }: SceneComponentProps<TextInterpolator>) {
  const { text } = model.useState();
  return (
    <div>
      <div style={{ marginBottom: 8 }}>
        <TextArea defaultValue={text} onBlur={(e) => model.onTextChange(e.currentTarget.value)} />
      </div>
      <pre>{model.state.text}</pre>
    </div>
  );
}

步骤 2. 使用`TextInterpolator`构建场景

使用TextInterpolator创建一个简单的场景。

const scene = new EmbeddedScene({
  body: new SceneFlexLayout({
    direction: 'column',
    children: [
      new SceneFlexItem({
        minHeight: 300,
        body: new TextInterpolator('Hello world'),
      }),
    ],
  }),
});

步骤 3. 向场景添加变量

定义一个自定义变量并将其添加到场景中。

const greetingsVar = new CustomVariable({
  name: 'greetings',
  query: 'Hello , Hola , Bonjour , Ahoj',
});

const scene = new EmbeddedScene({
  $variables: new SceneVariableSet({ variables: [greetingsVar] }),
  controls: [new VariableValueSelectors({})],
  body: new SceneFlexLayout({
    direction: 'column',
    children: [
      new SceneFlexItem({
        minHeight: 300,
        body: new TextInterpolator('Hello world'),
      }),
    ],
  }),
});

步骤 4. 向`TextInterpolator`对象添加变量支持

使用VariableDependencyConfig使TextInterpolator对变量更改做出反应。在TextInterpolator中定义一个protected _variableDependency 实例属性，该属性是VariableDependencyConfig的实例。

class TextInterpolator extends SceneObjectBase<TextInterpolatorState> {
  static Component = TextInterpolatorRenderer;

  protected _variableDependency = new VariableDependencyConfig(this, {
    statePaths: ['text'],
  });

  constructor(text: string) {
    super({ text });
  }

  onTextChange = (text: string) => {
    this.setState({ text });
  };
}

VariableDependencyConfig接受一个具有以下配置选项的对象

statePaths - 配置对象状态的哪些属性可以包含变量。使用['*']引用对象状态的任何属性。
onReferencedVariableValueChanged - 配置一个回调函数，当对象依赖的变量更改时将执行该回调函数。

注意

如果未为VariableDependencyConfig指定onReferencedVariableValueChanged，则对象默认会在变量更改时重新渲染。

步骤 5. 在组件中插值`text` 属性

在TextInterpolatorRenderer组件中，使用sceneGraph.interpolate帮助程序在变量更改时替换text属性中的变量。

function TextInterpolatorRenderer({ model }: SceneComponentProps<TextInterpolator>) {
  const { text } = model.useState();
  const interpolatedText = sceneGraph.interpolate(model, text);

  return (
    <div>
      <div style={{ marginBottom: 8 }}>
        <TextArea defaultValue={text} onBlur={(e) => model.onTextChange(e.currentTarget.value)} />
      </div>
      <pre>{interpolatedText}</pre>
    </div>
  );
}

以上代码将渲染一个包含模板变量、文本输入和预格式化文本块的场景。将文本输入中的文本修改为${greetings} World!，预格式化文本框将更新。更改场景顶部的变量值，这也会更新预格式化文本块。

自定义变量宏

您可以使用sceneUtils.registerVariableMacro注册自定义变量宏。变量宏对于您希望根据某些上下文动态计算的变量表达式很有用。作为宏实现的核心变量示例。

${__url.params:include:var-from,var-to}
${__user.login}

示例

export function getVariablesSceneWithCustomMacro() {
  const scene = new EmbeddedScene({
    // Attach the a behavior to the SceneApp or top level scene object that registers and unregisters the macro
    $behaviors: [registerMacro],
    controls: [new VariableValueSelectors({})],
    body: new SceneFlexLayout({
      direction: 'column',
      children: [
        new SceneFlexItem({
          minHeight: 300,
          body: new TextInterpolator('Testing my macro ${__sceneInfo.key}'),
        }),
      ],
    }),
  });

  return scene;
}

/**
 * Macro to support ${__sceneInfo.<stateKey>} which will evaluate to the state key value of the
 * context scene object where the string is interpolated.
 */
export class MyCoolMacro implements FormatVariable {
  public state: { name: string; type: string };

  public constructor(name: string, private _context: SceneObject) {
    this.state = { name: name, type: '__sceneInfo' };
  }

  public getValue(fieldPath?: string) {
    if (fieldPath) {
      return (this._context.state as any)[fieldPath];
    }

    return this._context.state.key!;
  }

  public getValueText?(): string {
    return '';
  }
}

function registerMacro() {
  const unregister = sceneUtils.registerVariableMacro('__sceneInfo', MyCoolMacro);
  return () => unregister();
}

等待变量

当您具有依赖于变量的状态逻辑时，您可以使用sceneGraph.hasVariableDependencyInLoadingState检查所有变量依赖项是否已准备好（非加载状态）。如果任何依赖项处于加载状态，则返回true，包括对完整依赖项链的检查。

对于同时订阅时间和变量的对象，我们建议使用VariableDependencyConfig及其onVariableUpdateCompleted回调和hasDependencyInLoadingState函数。由于变量也可以根据时间做出反应并发生变化，为了避免双重反应，VariableDependencyConfig具有内部状态来记住场景对象正在等待变量。要利用这一点，请指定onVariableUpdateCompleted回调。无论依赖项的值是否更改，或者场景对象是否正在等待变量，只要变量更新过程完成，此回调就会被调用。我们只关心它是否完成了加载。

示例设置

变量：A、B、C（B 依赖于 A，C 依赖于 B）。A 依赖于时间范围，因此每当时间范围更改时，它将加载新值，这可能导致新值（这将导致 B 和 C 也更新）。

具有依赖于变量 C 的查询的SceneQueryRunner

1. 时间范围更改值
1. 变量 A 开始加载
1. SceneQueryRunner 对时间范围更改做出响应，尝试启动新查询，但在发出新查询之前，调用variableDependency.hasDependencyInLoadingState。这会检查变量 C 是否正在加载，它没有加载，因此检查变量 B 是否正在加载（因为它是 C 的依赖项），它也没有加载，然后检查 A，A 正在加载，因此返回 true，并且 SceneQueryRunner 将跳过发出新查询。发生这种情况时，VariableDependencyConfig 将设置一个内部标志，表示它正在等待变量依赖项，这确保了当下一个变量完成时，会调用onVariableUpdateCompleted（无论完成的变量是否是直接依赖项，或者它是否已更改值，我们只关心它是否完成了加载）。
1. 变量 A 完成加载。选项（可能值）相同，因此没有更改值。
1. SceneQueryRunner 的 VariableDependencyConfig 收到通知，表明变量 A 已完成其加载阶段，因为它处于等待变量状态，因此即使 A 不是直接依赖项并且其值没有更改，它也会调用 onVariableUpdateCompleted 回调。

源代码

查看示例源代码

在自定义场景对象中使用变量​

步骤 1. 构建自定义场景对象​

步骤 2. 使用TextInterpolator构建场景​

步骤 3. 向场景添加变量​

步骤 4. 向TextInterpolator对象添加变量支持​

步骤 5. 在组件中插值text 属性​

自定义变量宏​

等待变量​

源代码​