设置JSON数据

本模块包只包含一个单独的组件DashJsonGrid。以下最小范例展示了如何上手使用该组件：

代码

minimal_example.py

import dash
import dash_json_grid as djg


app = dash.Dash("demo")
app.layout = djg.DashJsonGrid(
    data=1
)

if __name__ == "__main__":
    app.run()

结果

Dash应用应当呈现出以下结果：

1

1

数据整理

只需简单修改DashJsonGrid的参数data，即可观察到以下效果：

代码

...
app.layout = djg.DashJsonGrid(
    data=[1]
)
...

结果

Dash应用应当呈现出以下结果：

1

1

可以确认，相比上面的最小范例，此处的结果并未有任何变化。这是因为，所有传入data、却又不属于序列（Sequence）抑或映射（Mapping）的字面量，都会被自动转换成一个只含单元素的序列。换言之，data=1会被隐式整理为data=[1]。

提示

Dash 不会自动将一个定制的类序列化（serialize）。因此，如果data的结构中需要包含了定制类型的数据，建议将这些数据转换成str类型。

渲染一个序列

下例修改了data参数，并渲染了一个序列。

代码

...
app.layout = djg.DashJsonGrid(
    data=[1, 2.0, "3", None, True]
)
...

结果

Dash应用应当呈现出以下结果：

1	1
2	2
3	3
4	null
5	true

包含字面量或没有固定结构值的序列、会被渲染成纵向展开的列表。其中第一列显示序列下标、第二列显示序列的值。

渲染一个映射

下例修改了data参数，并渲染了一个映射。

代码

...
app.layout = djg.DashJsonGrid(
    data={"key1": 1, "key2": "str", "key3": True, "key4": None}
)
...

结果

Dash应用应当呈现出以下结果：

key1	1
key2	str
key3	true
key4	null

不属于表格成员的映射、会被渲染成纵向展开的列表。其中第一行代表映射关键字，第二行代表映射的值。

渲染一张表格

下例修改了data参数，并渲染了一张表格。

代码

...
app.layout = djg.DashJsonGrid(
    data=[
        {"key1": 1, "key2": "str"},
        {"key1": True, "key2": None},
        {"key1": 3.0},
        {"key1": False, "key2": None, "key3": 4.0},
        {"key5": "?"},
    ]
)
...

结果

Dash应用应当呈现出以下结果：

	key1	key2	key3	key5
1	1	str	undefined	undefined
2	true	null	undefined	undefined
3	3	undefined	undefined	undefined
4	false	null	4	undefined
5	undefined	undefined	undefined	?

当检查到一个序列（Sequence）所有的成员都是映射（Mapping）类型时，该序列会被渲染成一张表格，而非将序列本身渲染成带下标的列表的同时、将序列成员渲染成关键字列表。

表格的下标、对应了序列的下标。而表格的列名，对应的是序列中所有成员关键字的并集（union）。设若某行的数据中不存在某个关键字，对应的值将会被标记为未定义（undefined）。

渲染复杂、结构化的多级数据

下例展示了渲染复杂数据的效果。所用的多级数据中，表格、序列、和映射相互随意嵌套。DashJsonGrid能自动检查出如何妥善地渲染各级数据，从而帮助用户摆脱了手动将数据处理成多级HTML组件的繁琐过程。

代码

...
app.layout = djg.DashJsonGrid(
    data={
        "literal": 1,
        "sequence": [1, 2.0, "3", None, True],
        "mapping": {"key1": 1, "key2": "str", "key3": True, "key4": None},
        "table": [
            {"key1": 1, "key2": "str"},
            {"key1": True, "key2": None},
            {"key1": 3.0},
            {"key1": False, "key2": None, "key3": 4.0},
            {"key5": "?"},
        ],
        "not-a-table": [
            {"val1": 1},
            2.0,
            ["a", "b", "c"],
            [{"key1": ["a"], "key2": 2, "key3": {"val1": True}}],
            [{"key3": 1}],
        ],
    }
)
...

结果

Dash应用应当呈现出以下结果：

literal	1
sequence	[+]sequence [5]
mapping	[+]mapping {}
table	[+]table [5]
not-a-table	[+]not-a-table [5]

展开数据的一部分

处理形如上例中的复杂data属性时，有可能需要默认展开其中的一小部分。下例展示了如何透过属性default_expand_key_tree设置这种部分展开的特性：

代码

...
app.layout = djg.DashJsonGrid(
    data=...,
    default_expand_key_tree={"not-a-table": {"2": True}}
)
...

结果

Dash应用应当呈现出以下结果：

literal	1
sequence	[+]sequence [5]
mapping	[+]mapping {}
table	[+]table [5]
not-a-table	[-]not-a-table [5] 1 [+]0 {} 2 2 3 [-]2 [3] 1 a 2 b 3 c 4 [+]3 [1] 5 [+]4 [1]

注意default_expand_key_tree的叶子节点需要是二值量。设置为True的叶子节点，将展开对应的路由。

其他初始化组件的方法

在初始化组件的时候，数据还可以通过另外两种方式传递给组件。

透过字符串

用户还可以用JSON字符串初始化组件：

app.layout = dash_json_grid.DashJsonGrid.from_str(
    json_string: str, ...
)

使用该方法时，第一个参数json_string需要是可以被JSON解码的字符串。并且，参数data不可设置。

透过文件

还可以直接使用JSON文件来初始化组件：

app.layout = dash_json_grid.DashJsonGrid.from_file(
    json_file: str | os.PathLike | IO[str], ...
)

使用该方法时，第一个参数json_file可以是指向JSON文件的路径、或者类文件对象。并且，参数data不可设置。

注意

使用上述初始化时，json_string以及json_file会被自动转换为data。因此，json_string或json_file不可作为 callback 访问的组件属性。