Flutter动态JSON解析生成UI插件json_dynamic_widget的使用

json_dynamic_widget 是一个强大的Flutter库，它允许你通过JSON或YAML结构动态地创建和更新Flutter UI。这使得在运行时根据不同的配置文件构建界面成为可能，并且可以极大地提高开发效率和灵活性。

目录

• Live Example
• First Party Plugins
• IDE Extensions
• Migration to 7.X.X version
• Usage
• Understanding the Registry
• Built In Widgets
• Using Expressions
• Creating Custom Widgets
• Creating Custom Arg Processor

Live Example

你可以在线查看Web示例

First Party Plugins

以下是此库提供的官方插件列表：

• json_dynamic_widget_plugin_components
• json_dynamic_widget_plugin_font_awesome
• json_dynamic_widget_plugin_ionicons
• json_dynamic_widget_plugin_js
• json_dynamic_widget_plugin_lottie
• json_dynamic_widget_plugin_material_icons
• json_dynamic_widget_plugin_markdown
• json_dynamic_widget_plugin_rive
• json_dynamic_widget_plugin_svg

IDE Extensions

Visual Studio Code

• JSON Dynamic Widget Helper

Migration to 7.X.X version

从6.x版本迁移到7.x版本时，需要注意一些破坏性变更。这些变更可以通过Migration CLI自动完成。

Code Generation

自 7.0.0 版本开始，引入了代码生成器来简化动态小部件的创建。下面展示了 >= 7.0.0 和 < 7.0.0 的差异。

>= 7.0.0

import 'package:json_dynamic_widget/json_dynamic_widget.dart';

part 'json_column_builder.g.dart';

@jsonWidget
abstract class _JsonColumnBuilder extends JsonWidgetBuilder {
  const _JsonColumnBuilder({
    required super.args,
  });

  @override
  Column buildCustom({
    ChildWidgetBuilder? childBuilder,
    required BuildContext context,
    required JsonWidgetData data,
    Key? key,
  });
}

< 7.0.0

import 'package:child_builder/child_builder.dart';
import 'package:flutter/material.dart';
import 'package:json_dynamic_widget/json_dynamic_widget.dart';
import 'package:json_theme/json_theme.dart';
import 'package:json_theme/json_theme_schemas.dart';

class JsonColumnBuilder extends JsonWidgetBuilder {
  const JsonColumnBuilder({
    required this.crossAxisAlignment,
    required this.mainAxisAlignment,
    required this.mainAxisSize,
    this.textBaseline,
    this.textDirection,
    required this.verticalDirection,
  }) : super(numSupportedChildren: kNumSupportedChildren);

  static const kNumSupportedChildren = -1;

  static const type = 'column';

  final CrossAxisAlignment crossAxisAlignment;
  final MainAxisAlignment mainAxisAlignment;
  final MainAxisSize mainAxisSize;
  final TextBaseline? textBaseline;
  final TextDirection? textDirection;
  final VerticalDirection verticalDirection;

  static JsonColumnBuilder? fromDynamic(
    dynamic map, {
    JsonWidgetRegistry? registry,
  }) {
    JsonColumnBuilder? result;

    if (map != null) {
      result = JsonColumnBuilder(
        crossAxisAlignment: ThemeDecoder.decodeCrossAxisAlignment(
              map['crossAxisAlignment'],
              validate: false,
            ) ??
            CrossAxisAlignment.center,
        mainAxisAlignment: ThemeDecoder.decodeMainAxisAlignment(
              map['mainAxisAlignment'],
              validate: false,
            ) ??
            MainAxisAlignment.start,
        mainAxisSize: ThemeDecoder.decodeMainAxisSize(
              map['mainAxisSize'],
              validate: false,
            ) ??
            MainAxisSize.max,
        textBaseline: ThemeDecoder.decodeTextBaseline(
          map['textBaseline'],
          validate: false,
        ),
        textDirection: ThemeDecoder.decodeTextDirection(
          map['textDirection'],
          validate: false,
        ),
        verticalDirection: ThemeDecoder.decodeVerticalDirection(
              map['verticalDirection'],
              validate: false,
            ) ??
            VerticalDirection.down,
      );
    }

    return result;
  }

  @override
  Widget buildCustom({
    ChildWidgetBuilder? childBuilder,
    required BuildContext context,
    required JsonWidgetData data,
    Key? key,
  }) {
    return Column(
      crossAxisAlignment: crossAxisAlignment,
      key: key,
      mainAxisAlignment: mainAxisAlignment,
      mainAxisSize: mainAxisSize,
      textBaseline: textBaseline,
      textDirection: textDirection,
      verticalDirection: verticalDirection,
      children: [
        for (var child in data.children ?? <JsonWidgetData>[])
          child.build(
            context: context,
            childBuilder: childBuilder,
          ),
      ],
    );
  }
}

class ColumnSchema {
  static const id =
      'https://peiffer-innovations.github.io/flutter_json_schemas'
        '/schemas/json_dynamic_widget/column.json';

  static final schema = {
    r'$schema': 'http://json-schema.org/draft-06/schema#',
    r'$id': id,
    r'$children': -1,
    r'$comment': 'https://api.flutter.dev/flutter/widgets/Column-class.html',
    'title': 'Column',
    'oneOf': [
      {
        'type': 'null',
      },
      {
        'type': 'object',
        'additionalProperties': false,
        'properties': {
          'crossAxisAlignment':
              SchemaHelper.objectSchema(CrossAxisAlignmentSchema.id),
          'mainAxisAlignment':
              SchemaHelper.objectSchema(MainAxisAlignmentSchema.id),
          'mainAxisSize': SchemaHelper.objectSchema(MainAxisSizeSchema.id),
          'textBaseline': SchemaHelper.objectSchema(TextBaselineSchema.id),
          'textDirection': SchemaHelper.objectSchema(TextDirectionSchema.id),
          'verticalDirection':
              SchemaHelper.objectSchema(VerticalDirectionSchema.id),
        },
      },
    ],
  };
}

Migration CLI

要迁移现有JSON/YAML文件，请首先将包添加为依赖项：

dependencies:
  json_dynamic_widget: <version>

然后运行：

dart run json_dynamic_widget:migrate_7 [path/to/files]

Usage

由于该库允许动态构建图标，Flutter内置的图标树抖动功能不再能保证哪些图标被引用。因此，必须添加 --no-tree-shake-icons 标志进行构建。

flutter build [apk | web | ios | ...] --no-tree-shake-icons

JSON结构示例

{
  "type": "<lower_case_type>",
  "id": "<optional-id>",
  "listen": [
    "var1",
    "var2",
    "..."
  ],
  "args": {
    "...": "..."
  },
}

YAML结构示例

---
type: <lower_case_type>
id: <optional-id>
listen: 
  - var1
  - var2
  - ...
args:
  ...: ...

示例代码

import 'package:flutter/material.dart';
import 'package:json_dynamic_widget/json_dynamic_widget.dart';

class MyStatefulWidget extends StatefulWidget {
  MyStatefulWidget({
    @required this.jsonData,
    this.registry,
    Key key,
  }): assert(jsonData != null),
    super(key: key)

  final Map<String, dynamic> jsonData;
  final JsonWidgetRegistry registry;

  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyStatefulWidget> {
  late JsonWidgetData _data;

  @override
  void initState() {
    super.initState();

    _data = JsonWidgetData.fromDynamic(widget.jsonData);
  }

  @override
  Widget build(BuildContext context) => _data.build(
    context, 
    registry: widget.registry ?? JsonWidgetRegistry.instance,
  );
}

Understanding the Registry

JsonWidgetRegistry 是集中处理JSON动态小部件的中心仓库。它负责注册小部件、提供动态变量和函数，以及处理参数处理器。

Built In Widgets

所有内部构造器默认都会添加到注册表中。例如，align 构造器可以在 align.json 中找到示例。

Using Expressions

自4.0.0版本以来，该库与 expressions 库紧密集成，可以在JSON中定义表达式。

使用变量

变量可以在用于渲染动态小部件的 JsonWidgetRegistry 中定义。例如：

${dynamicVariable}
${dynamic['persons'][0]}
${'Hello ' + name}

动态函数

基本用法

${sayHello('Hello,' + firstName)}

命名参数

${myFunction({'key':'keyName', 'value':value})}

复杂调用

${func1(func2(func3()+' text'+var1), func4(1+2))}

Creating Custom Widgets

创建自定义小部件需要首先创建一个 JsonWidgetBuilder 。例如，创建一个SVG渲染小部件：

import 'package:flutter_svg/flutter_svg.dart';
import 'package:json_dynamic_widget/json_dynamic_widget.dart';

part 'svg_builder.g.dart';

@jsonWidget
abstract class _SvgBuilder extends JsonWidgetBuilder {
  const _SvgBuilder({
    required super.args,
  });

  @override
  _Svg buildCustom({
    ChildWidgetBuilder? childBuilder,
    required BuildContext context,
    required JsonWidgetData data,
    Key? key,
  });
}

class _Svg extends StatelessWidget {
  const _Svg({
    this.asset,
    this.color,
    this.height,
    this.url,
    this.width,
  })  : assert(asset == null || url == null),
        assert(asset != null || url != null);

  final String? asset;
  final Color? color;
  final double? height;
  final String? url;
  final double? width;

  @override
  Widget build(BuildContext context) {
    return asset != null
        ? SvgPicture.asset(
            asset!,
            height: height,
            width: width,
          )
        : SvgPicture.network(
            url!,
            height: height,
            width: width,
          );
  }
}

然后运行代码生成命令：

dart run build_runner build --delete-conflicting-outputs

最后，使用以下JSON构造实例：

{
  "type": "svg",
  "args": {
    "asset": "assets/images/visa.svg",
    "color": "#fff",
    "height": 40,
    "width": 56
  }
}

Creating Custom Arg Processor

为了扩展JSON语法，可以创建自定义参数处理器。例如，将 "TRUE" 和 "FALSE" 转换为布尔值：

import 'package:json_dynamic_widget/json_dynamic_widget.dart';

class BooleanStringArgProcessor implements ArgProcessor {
  final _matchRegexp = RegExp(r'^TRUE|FALSE$');

  @override
  bool support(dynamic arg) {
    return arg != null && arg is String && _matchRegexp.hasMatch(arg);
  }

  @override
  ProcessedArg process(
      JsonWidgetRegistry registry, dynamic arg, Set<String>? listenVariables) {
    var resultListenVariables = listenVariables ?? <String>{};
    var boolStr = _matchRegexp.firstMatch(arg)!.toString();
    return ProcessedArg(
        listenVariables: resultListenVariables,
        value: boolStr == 'TRUE',
    );
  }
}

var registry = JsonWidgetRegistry.instance;

registry.registerArgProcessors(
   <ArgProcessor>[BooleanStringArgProcessor()].addAll(ArgProcessors.defaults)
);

以上是 json_dynamic_widget 插件的主要内容和使用方法。希望对你有所帮助！