自定义场景对象中的变量
变量 为交互式仪表板奠定了基础。它们允许动态配置查询哪些数据。
除了标准的变量支持外,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
中定义一个受保护的 _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 也更新)。
SceneQueryRunner,其查询依赖于变量 C
-
- 时间范围更改值
-
- 变量 A 开始加载
-
- SceneQueryRunner 响应时间范围更改,尝试启动新查询,但在发出新查询之前,调用
variableDependency.hasDependencyInLoadingState
。这会检查变量 C 是否正在加载,但它没有加载,因此然后检查变量 B 是否正在加载(因为它是 C 的依赖项),它也没有加载,因此然后检查 A,A 正在加载,因此它返回 true,SceneQueryRunner 将跳过发出新查询。发生这种情况时,VariableDependencyConfig 将设置一个内部标志,表明它正在等待变量依赖项,这确保了在下一个变量完成时,无论完成的变量是否是直接依赖项,或者它是否已更改值,都会调用 onVariableUpdateCompleted 回调(我们只关心它完成了加载)。
- SceneQueryRunner 响应时间范围更改,尝试启动新查询,但在发出新查询之前,调用
-
- 变量 A 完成加载。选项(可能的值)相同,因此没有更改值。
-
- SceneQueryRunner 的 VariableDependencyConfig 收到变量 A 已完成其加载阶段的通知,因为它处于等待变量状态,即使 A 不是直接依赖项且未更改值,它也会调用 onVariableUpdateCompleted 回调。