DashJsonGrid

类组件源码

comp = DashJsonGrid(
    id: str | Mapping,
    class_name: str,
    style: Mapping,
    data: Any,
    default_expand_depth: int,
    default_expand_key_tree: Mapping,
    selected_path: list ,
    highlight_selected: bool,
    search_text: str,
    theme: str | ThemeConfigs,
    loading_state: LoadingState
)

DashJsonGrid组件是对React项目react-json-grid/JSONGrid的Dash移植版。

该组件针对复杂、无固定结构、可序列化的JSON数据，提供了网格视图可视化。

组件属性

描述

名称	类型	说明
id	str | Mapping[str, Any]	组件ID。若设置为字典，则该ID用于[模式匹配callback :book:][dash-pmcallback].
class_name	str	组件的CSS类。使用 分隔不同的类。
style	Mapping[str, str]	组件的CSS样式。这些样式用于覆盖组件容器的默认样式。.
data	Any	用来转换成网格视图的数据，其支持JSON序列化。
default_expand_depth	int	无用户交互时，默认状态下网格展开的深度。
default_expand_key_tree	Mapping[Any, Any]	需要展开的所有关键字，这些关键字定义成树状结构，且只能在data是映射（Mapping）的情况下生效。
selected_path	list	用来表示当前选中元素的路由，该路由是按顺序排列的下标组成的序列，其中最后一个值可以是一个只含单值的列表，以表示选中的是表格、或表格的列。
highlight_selected	bool	用来控制是否允许被选中的区域高亮。禁用该值会阻止由用户选择发出的 callback。
search_text	str	用来在JSON数据中搜索、高亮数据时，进行快速查询的关键字。
theme	str | ThemeConfigs	主题名称、或包含主题详细信息的字典。
loading_state	LoadingState	Dash的加载状态字典。用户不应手动设置该值。

参数

名称	类型	可交互	可设置	必选	默认值
id	str | Mapping[str, Any]				undefined
class_name	str				undefined
style	Mapping[str, str]				undefined
data	Any
default_expand_depth	int				0
default_expand_key_tree	Mapping[Any, Any]				undefined
selected_path	list				[]
highlight_selected	bool				True
search_text	str				undefined
theme	str | ThemeConfigs				"default"
loading_state	LoadingState				undefined

• “可交互”指的是，用户交互可以改变该属性、并触发callback。
• “可设置”指的是，透过callback的Output(...)修改该值会产生实际效果。
• “必选”指的是，初始化组件时，必须向组件传递值，否则组件无法初始化。

方法

compare_routes

flag: bool = mixin.compare_routes(route_1: Route, route_2: Route)

比对两个不同的路由，其中Route数据类型的参数即selected_path的值。

交换输入参数的位置，比对结果不变。该方法可以检测route_1和route_2是否指向同一位置。

输入

参数	类型	必选	说明
route_1 route_2	Route		selected_path触发callback时提供的路由。各元素为按照路由的先后次序排列的下标。末位元素可能是一个单元素序列，以用来表示被选中的区域是表格、或表格的列。

输出

参数	类型	说明
flag	bool	二值量。取True时，表示route_1和route_2指向的位置相同。

---

get_data_by_route

data_selected: Any = mixin.get_data_by_route(data: Any, route: Route)

透过某路由来获得其对应的区域的部分数据。

输入

参数	类型	必选	说明
data	Any		用来进行路由的完整数据。
route	Route		用来定位data数据的某一特定部分的路由，由数据各级下标构成。若末位元素route定位到表格的列，则输出由列中的每个元素构成的序列。

输出

参数	类型	说明
data_selected	Any	由route选中的部分数据。

---

update_data_by_route

data: Any = mixin.update_data_by_route(data: Any, route: Route, val: Any)

按照路由定位数据的某一部分、并更新该部分的值。

设若更新失败（譬如，数据被设置成不可变的情况下），则抛出ValueError。

输入

参数	类型	必选	说明
data	Any		将要更新的完整数据。
route	Route		用来定位data数据的某一特定部分的路由，由数据各级下标构成。若末位元素route定位到表格的列，则透过广播更新列中的每个元素。
val	Any		更新给定数据的某一部分时，用来替换原数据的新值。若将要更新的数据是表格列，该val值可以被广播到列的各个值上。若广播失败，抛出IndexError。

输出

参数	类型	说明
data	Any	更新后的data。由于data本身是可变的，即使这个返回值没有被实际用到，对数据的修改依然是有效的。

---

delete_data_by_route

data_selected: Any = mixin.delete_data_by_route(data: Any, route: Route)

按照路由定位数据的某一部分、并删除该部分的值。

设若删除失败（譬如，数据被设置成不可变的情况下），则抛出ValueError。

输入

参数	类型	必选	说明
data	Any		将要修改的完整数据，其中被选中的部分会被删除。
route	Route		用来定位data数据的某一特定部分的路由，由数据各级下标构成。若末位元素route定位到表格的列，则移除并弹出由列中的每个元素构成的序列。

输出

参数	类型	说明
data_selected	Any	被删除并从数据中弹出的部分。

---

from_str

comp = DashJsonGrid.from_str(json_string: str, *args, **kwargs)

from_str是类方法，该方法初始化并返回一个实例。

使用JSON格式的字符串以初始化该组件。

使用该方法时，参数data需要留空，该方法会透过载入json_string将值传递给参数data。

输入

参数	类型	必选	说明
json_string	str		由JSON数据编码的字符串。
*args, **kwargs	...		与初始化的参数相同，参见组件属性。唯一例外的是data，因为json_string取代了该值。

输出

参数	类型	说明
comp	DashJsonGrid	由json_string初始化的组件，其他的细节和常规初始化的组件相同。

---

from_file

comp = DashJsonGrid.from_file(
    json_file: str | os.PathLike | IO[str], *args, **kwargs
)

from_file是类方法，该方法初始化并返回一个实例。

使用JSON文件以初始化该组件。

使用该方法时，参数data需要留空，该方法会透过载入json_file将值传递给参数data。

输入

参数	类型	必选	说明
json_file	str | os.PathLike | IO[str]		设若给定的参数类型是str | os.PathLike，该参数将作为载入文件的路径，文件内容载入为传入数据。 设若该值是IO[str]，则直接载入该类文件对象。
*args, **kwargs	...		与初始化的参数相同，参见组件属性。唯一例外的是data，因为json_file取代了该值。

输出

参数	类型	说明
comp	DashJsonGrid	由json_file初始化的组件，其他的细节和常规初始化的组件相同。

范例

以路由定位值

代码

get_data_by_route.py

import pprint
from dash_json_grid import DashJsonGrid

data = {
    "id": "0001",
    "type": "donut",
    "name": "Cake",
    "ppu": 1111.55,
    "batters": {
        "batter": [
            {"id": "1001", "type": "Regular"},
            {"id": "1002", "type": "Chocolate"},
            {"id": "1003", "type": "Blueberry"},
            {"id": "1004", "type": "Devil's Food"},
        ]
    },
    "topping": [
        {"id": "5001", "type": "None"},
        {"id": "5002", "type": "Glazed"},
        {"id": "5005", "type": "Sugar"},
        {"id": "5007", "type": "Powdered Sugar"},
        {"id": "5006", "type": "Chocolate with Sprinkles"},
        {"id": "5003", "type": "Chocolate"},
        {"id": "5004", "type": "Maple"},
    ],
}

pprint.pprint(DashJsonGrid.get_data_by_route(data, ["batters", "batter", 0, "id"]))
pprint.pprint(DashJsonGrid.get_data_by_route(data, ["batters", "batter", 0, ["id"]]))
pprint.pprint(DashJsonGrid.get_data_by_route(data, ["batters", "batter", ["id"]]))

结果

'1001'
'1001'
('1001', '1002', '1003', '1004')

以路由更新表格的列/行

代码

update_data_by_route.py

import pprint
from dash_json_grid import DashJsonGrid

data = [
    {"key1": 1, "key2": "str"},
    {"key1": True, "key2": None},
    {"key1": 3.0},
    {"key1": False, "key2": None, "key3": 4.0},
    {"key5": "?"},
]

pprint.pprint(DashJsonGrid.update_data_by_route(data, [["key3"]], 1))
pprint.pprint(DashJsonGrid.update_data_by_route(data, [0], {"only": "test2"}))

结果

[{'key1': 1, 'key2': 'str', 'key3': 1},
 {'key1': True, 'key2': None, 'key3': 1},
 {'key1': 3.0, 'key3': 1},
 {'key1': False, 'key2': None, 'key3': 1},
 {'key3': 1, 'key5': '?'}]
[{'only': 'test2'},
 {'key1': True, 'key2': None, 'key3': 1},
 {'key1': 3.0, 'key3': 1},
 {'key1': False, 'key2': None, 'key3': 1},
 {'key3': 1, 'key5': '?'}]

以路由删除表格的列/行

代码

delete_data_by_route.py

import pprint
from dash_json_grid import DashJsonGrid

data = [
    {"key1": 1, "key2": "str"},
    {"key1": True, "key2": None},
    {"key1": 3.0},
    {"key1": False, "key2": None, "key3": 4.0},
    {"key5": "?"},
]

pprint.pprint(DashJsonGrid.delete_data_by_route(data, [["key3"]]))
pprint.pprint(data)
pprint.pprint(DashJsonGrid.delete_data_by_route(data, [0]))
pprint.pprint(data)

结果

(None, None, None, 4.0, None)
[{'key1': 1, 'key2': 'str'},
 {'key1': True, 'key2': None},
 {'key1': 3.0},
 {'key1': False, 'key2': None},
 {'key5': '?'}]
{'key1': 1, 'key2': 'str'}
[{'key1': True, 'key2': None},
 {'key1': 3.0},
 {'key1': False, 'key2': None},
 {'key5': '?'}]

警告

使用dash_json_grid<=0.3.2时，运行该范例会触发KeyError: 'key3'。因为0.3.3版之前，该方法只能删除存在于原数据之中的关键字。

检查路由是否合乎期望

callback_compare_routes.py

@app.callback(
    Output(...),
    Input("grid", "selected_path")  # "grid"是DashJsonGrid组件
)
def check_route(route):
    if DashJsonGrid.compare_routes(route, [1, "new", ["column"]]):
        # 当且仅当[1, "new", ["column"]]时，进行某些处理
        ...

获取选中的数据

callback_get_selected.py

@app.callback(
    Output(...),
    Input("grid", "selected_path"),  # "grid"是DashJsonGrid组件
    State("grid", "data")
)
def show_data(route, data):
    data_part = DashJsonGrid.get_data_by_route(data, route)
    ...

修改选中的数据

callback_modify_selected.py

@app.callback(
    Output("grid", "data"),  # "grid"是DashJsonGrid组件
    Input("grid", "selected_path"),
    State("grid", "data")
)
def modify_data(route, data):
    data_part = DashJsonGrid.get_data_by_route(data, route)
    modified_part = ...  # 做一些修改
    DashJsonGrid.update_data_by_route(data, route, modified_part)
    return data
    ...

删除选中的数据

callback_delete_selected.py

@app.callback(
    Output("grid", "data"),  # "grid"是DashJsonGrid组件
    Input("grid", "selected_path"),
    State("grid", "data")
)
def delete_data(route, data):
    deleted_part = DashJsonGrid.delete_data_by_route(data, route)
    # deleted_part是从完整数据中移除的部分
    return data