Skip to content

Latest commit

 

History

History
849 lines (621 loc) · 39.7 KB

DOCUMENTATION_CN.md

File metadata and controls

849 lines (621 loc) · 39.7 KB
Raw

English README

如何使用 | 例子 | 参数说明 | 查看新功能

安装和使用

  • 安装

    pip install ctkchart

  • 使用

    import ctkchart

参数概述

要使用 ctkchart 显示数据，您需要执行以下三步：

  1. 创建折线图
  2. 创建一条线
  3. 数据显示

1 . 创建折线图

创建一条线 | 数据显示

linechart = ctkchart.CTkLineChart()

参数

参数 必备参数 / 可选参数 描述 数据类型 示例值
master 必须 折线图主体 widget widget
y_axis_values 必须 y 轴的最小值和最大值 tuple[int | float], ... (-1000, 1000), ...
x_axis_values 必须 x 轴的值 tuple[any, ...] (1, 2, 3, 4, 5), ...
width 可选 折线图的宽度 int 300, ...
height 可选 折线图的高度 int 100, ...
axis_size 可选 坐标轴宽度 int 1<=
axis_color 可选 坐标轴轴颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), ...
bg_color 可选 折线图的背景色 tuple[str, str] | str ("#FF0000", "#00FF00"), ...
fg_color 可选 折线图的前景色 tuple[str, str] | str ("#FF0000", "#00FF00"), ...
data_font_style 可选 坐标轴名称的字体样式 tuple[str, int, str] ("arial", 9, "bold"), ...
axis_font_style 可选 坐标轴文字的字体样式 tuple[str, int, str] ("arial", 8, "normal"), ...
x_axis_data 可选 x_data 的值（x 坐标轴名称） str "X", ...
y_axis_data 可选 y_data 的值（y 坐标轴名称） any "Y", ...
x_axis_data_font_color 可选 x_data 的字体颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#707070", ...
y_axis_data_font_color 可选 y_data 的字体颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#707070", ...
x_axis_data_position 可选 x_data 的排布方式 str "top"
y_axis_data_position 可选 y_data 的排布方式 str "top"
x_axis_section_count 可选 x 轴上的网格线数 int 0<=
y_axis_section_count 可选 y 轴上的网格线数 int 0<=
x_axis_label_count 可选 x 轴标签数量 int 0<=
y_axis_label_count 可选 y 轴标签数量 int 1<=
x_axis_font_color 可选 x 轴标签的字体颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#606060", ...
y_axis_font_color 可选 y 轴标签的字体颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#606060", ...
x_axis_section_style 可选 x 轴上的网格线样式 str "normal"
y_axis_section_style 可选 y 轴上的网格线样式 str "normal"
x_axis_section_style_type 可选 x 轴上网格线的实线与空白的尺寸 tuple[int, int] (100, 50) , (50,50), ...
y_axis_section_style_type 可选 y 轴上网格线的实线与空白的尺寸 tuple[int, int] (100, 50)
x_axis_section_color 可选 x 轴上网格线的颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#2C2C2C", ...
y_axis_section_color 可选 y 轴上网格线的颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#2C2C2C"
y_axis_precision 可选 y 轴值的精度 int 0<=
x_axis_display_values_indices 可选 显示在 x 轴上的坐标值的索引 tuple[int, ...] (0, 1, 2, 3, 4, 5), ...
x_axis_point_spacing 可选 线条宽度 int | str "auto" "auto"
1<=
x_space 可选 x 轴和图表区域之间的空间 int 0<=
y_space 可选 y 轴和图表区域之间的空间 int 0<=
pointer_state 可选 鼠标状态 str ("enabled", "disabled") "disabled"
pointing_callback_function 可选 鼠标的回调函数 callable function(*args)
function(x, y)
pointer_color 可选 鼠标颜色 tuple[str, str] | str ("#FF0000", "#00FF00"), "#606060", ...
pointing_values_precision 可选 指向值的精度 int 0<=
pointer_lock 可选 鼠标锁状态 str ("enabled", "disabled") "enabled"
pointer_size 可选 鼠标显示线的宽度 int 1<=

方法

方法 描述 支持的参数 / 必须的参数 返回类型
configure 更改 LineChart（折线图）属性 所有属性，除了 master None
show_data 显示数据 data: list
line: ctkchart.CTkLine		 None
place 放置 (place) 折线图 x: int
y: int
rely: float or int
relx: float or int
anchor: str		 None
pack 放置 (pack) 折线图 pady: int
padx: int
before: widget
after: widget
side: str
anchor: str		 None
grid 放置 (grid) 折线图 column: int
columnspan: int
padx: int
pady: int
row: int
rowspan: int
sticky: str		 None
place_forget Place 忘编号 - None
pack_forget Pack 忘编号 - None
grid_forget Grid 忘编号 - None
set_lines_visibility 更改所有线条的可见性 state: bool None
set_line_visibility 更改特定行的可见性 line: ctkchart.CTkLine
state: bool		 None
get_line_visibility 获取特定生产线的可见性 line: ctkchart.CTkLine bool
reset 重置折线图 - None
cget 获取指定参数的值。 attribute_name: str | "__all__" any
place_info 获取地点信息 attribute_name: str | "__all__" any
pack_info 获取有关包装的信息 attribute_name: str | "__all__" any
grid_info 获取网格信息 attribute_name: str | "__all__" any
get_line_area 获取特定线的面积 line: ctkchart.CTkLine float
get_lines_area 获取所有线的面积 - float
destroy 销毁图表 - None

2 . 创建一条线

创建折线图 | 数据显示

line = ctkchart.CTkLine()

参数

参数名称 必备参数 / 可选参数 描述 数据类型 示例值
master 必须 Master ctkchart.CTkLine LineChart obj
color 可选 折线的颜色 str "#768df1"
size 可选 Size of the line int 1<=
style 可选 折线风格（直线、虚线、点线） str ("normal", "dashed", "dotted") "normal"
style_type 可选 实线与虚线的尺寸 tuple[int, int] (10, 5),...
point_highlight 可选 端点高亮状态 str ("enabled", "disabled") "disabled"
point_highlight_size 可选 高亮点的大小 int 1<=
point_highlight_color 可选 高亮点的颜色 str "#768df1"
fill 可选 是否启用填充 str ("enabled", "disabled") "disabled"
fill_color 可选 填充部分的颜​​色 str "#5d6db6"

方法

方法 描述 支持的参数 返回类型
configure 更改折线图属性 所有属性，除了 master None
cget 获取指定参数的值 attribute_name: str | "__all__" any
reset 重置线对象 - None
set_visible 改变线条的可见度 state: bool None
get_visibility 获得线路的可见度 - bool
destroy 破坏线 - None

3 . 数据显示

创建折线图 | 创建一条折线

import tkinter as tk 
import ctkchart 
import random 

## root 
root = tk.Tk() 
root.configure(bg="#151515") 

## 创建折线图 
chart = ctkchart.CTkLineChart(
    master=root, 
    x_axis_values = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10), 
    y_axis_values = (-100,100)
) 
chart.pack() 

## 创建一条折线 
line = ctkchart.CTkLine(master=chart) 

data = [x for x in range(-100,101)] #values -100 to 100 
## 显示数据（随机） 
def loop(): 
    chart.show_data(line=line, data=random.choices(data, k=1)) 
    root.after(500, loop) 
loop() 

root.mainloop()
output.mp4

返回顶部 | 使用指南 | 例子 | 查看新功能

参数说明

CTkLineChart

  • y_axis_values

    y_axis_values 是一个包含两个数值的元组。第一个值（索引 0）表示 y 轴的起始值，第二个值（索引 1）表示 y 轴的结束值。该元组定义了折线图上沿 y 轴显示的值的范围。

  • x_axis_values

    x_axis_values 是可以包含任何数据类型的值的集合。这些值被分配给 x 轴，从索引 0 开始一直到 x_axis_values 元组的最后一个索引。元组中的每个值对应于折线图中 x 轴上的一个点。

    chart = ctkchart.CTkLineChart(
    master=any_widget,
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100) 
)

  • x_axis_data

    指折线图 x 轴上显示的值类型。 注意："X"为默认值。

  • y_axis_data

    指折线图 y 轴上显示的值类型。 注意："Y" 是默认值。

  • x_axis_data_font_color

    指应用于表示折线图 x_axis_data 的标签的字体颜色。

  • y_axis_data_font_color

    指应用于表示折线图 y_axis_data 的标签的字体颜色。

  • data_font_style

    指应用于代表折线图 x_axis_data 和 y_axis_data 的标签的字体样式。

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    y_axis_data="Y data" , 
    x_axis_data="X data", 
    x_axis_data_font_color="#ff0000", 
    y_axis_data_font_color="#00ff00", 
    data_font_style=("arial", 15, "underline") 
)

  • x_axis_label_count

    当您有一组 x_value（例如从 2018 年到 2025 年）时，通常会显示所有这些标签。但有时为了更清晰起见，您可能只想显示其中的几个。
    例如，如果您将 x_axis_label_count 设置为 4，则意味着您只想显示 4 个标签，而不是全部 8 个。因此，折线图将自动跳过一些标签以适合您指定的数量。
    注意：len(x_axis_values) 是默认值。
    换句话说，调整 x_axis_label_count 可以让您控制 x 轴上显示的标签数量，使您的可视化更清晰、更易于理解。
    -如果有 9 个标签，您可以将其限制为：3、1。 -如果有 20 个标签，您可以将其限制为：10, 5, 4, 2, 1。 -如果有 15 个标签，您可以将其限制为：5、3、1。

    在某些情况下，使用 x_axis_label_count 参数可能不足以满足您的需求。在这种情况下，您可以利用 x_axis_display_values_indices 参数来精确控制 x 轴上显示的值。

  • y_axis_label_count

    默认情况下，如果将 y 轴值设置为 -100 到 100 范围，则 y 轴上将仅显示极值（-100 和 100 两个数字）。但是，您可以选择使用 y_axis_label_count 参数调整显示的标签数量。
    例如，如果将 y_axis_label_count 设置为 3，系统会将 y 轴范围（-100 到 100）划分为相等的间隔，并按这些间隔显示标签。因此，对于本例，标签计数为 3，您可能会看到 -100、0 和 100 处的标签。
    总之，调整 y_axis_label_count 参数允许您控制 y 轴上显示的标签数量，从而可以根据您的偏好和要求灵活地自定义可视化效果。

    chart = ctkchart.CTkLineChart(
    master=any_widget,
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_label_count=4, 
    y_axis_label_count=10
)

  • x_axis_display_values_indices

    假设您有一组代表从 2018 年到 2025 年的 x 轴值：(2018、2019、2020、2021、2022、2023、2024、2025)。通常，所有这些值都会显示在 x 轴上。
    但是，在某些情况下，您可能只想显示特定年份而不是全部。在这种情况下，您可以使用 x_axis_display_values_indices 参数来控制在 x 轴上显示哪些值。
    例如，如果您只想显示 2019 年、2022 年和 2025 年，则可以在 x_axis_display_values_indices 参数中指定它们的索引。因此，如果 2019 年的索引为 1、2022 年为 4、2025 年为 7（假设基于 0 的索引），则您可以将 x_axis_display_values_indices 设置为 (1, 4, 7)。
    这样，通过设置要显示的值的索引，您可以精确控制可视化中 X 轴上显示的值，从而允许您根据您的特定要求对其进行定制。

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_display_values_indices=(1, 4, 7)
)

  • x_axis_data_position

    x_axis_data_position 参数确定 x_axis_data 的文字布局。

    它有两个支持的值：

    • "top"
    • "side"

    注意：“top”是默认位置

  • y_axis_data_position

    y_axis_data_position 参数确定 y_axis_data 的文字布局。

    它有两个支持的值：

    • "top"
    • "side"

    注意：“top”是默认位置


    在"top"、"side"之间进行选择分别确定 x/y_axis_data 是水平放置在数据点上方还是垂直放置在数据点旁边。此参数允许您根据您的喜好和可用空间自定义折线图的布局。

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_data_position="side", 
    y_axis_data_position="top" 
)

  • y_axis_precision

    y_axis_ precision 参数控制 y 轴上的值显示的小数位数。
    注意：1 是默认精度
    例如：

    • 如果将 y_axis_precision 设置为 0，则 y 轴上的值将显示为整数。
    • 如果将 y_axis_precision 设置为 1，则 y 轴上的值将显示一位小数。
    • 如果将 y_axis_precision 设置为 2，则 y 轴上的值将显示两位小数。

    此外 :

    • 调整 y_axis_ precision 参数允许您控制折线图中 y 轴值的精度级别。当处理需要特定精度的数据或当您想要通过减少显示的小数位数来提高折线图的可读性时，此参数特别有用。
    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    y_axis_label_count=12, 
    y_axis_precision=4, 
)

  • axis_font_style

    指 x 和 y 轴值的字体样式

  • x_axis_font_color

    指 x 轴值的颜色

  • y_axis_font_color

    指 y 轴值的颜色

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_values=(2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025), 
    y_axis_values=(-100, 100), 
    x_axis_font_color="#00FF00", 
    y_axis_font_color="#FF0000", 
    axis_font_style=("arial", 13, "bold") 
)

  • x_axis_section_count

    x_axis_section_count 参数定义折线图中 x 轴范围将划分为的部分或间隔的数量。
    这里有更清晰的细分：
    • 假设 x 轴上有一系列值，例如从 2018 年到 2025 年。默认情况下，此范围可能表示为连续线，没有标记任何特定部分或间隔。
    • 但是，如果将 x_axis_section_count 设置为一个值，例如 8，则意味着您想要将此 x 轴范围划分为等间距的部分或间隔。每个部分将代表总 x 轴范围的一个子集。
    • 调整 x_axis_section_count 参数允许您控制折线图中 x 轴的粒度，使查看者更容易解释数据并识别特定间隔内的趋势。

  • y_axis_section_count

    y_axis_section_count 参数定义折线图中 y 轴范围将划分为的部分或间隔的数量。
    请参阅：x_axis_section_count 了解更多...

  • x_axis_section_color

    指 y 轴网格线的颜色

  • y_axis_section_color

    指 x 轴网格线的颜色

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_section_count=8, 
    y_axis_section_count=5, 
    x_axis_section_color="#2C2C2C", 
    y_axis_section_color="#2C2C2C" 
)

  • x_axis_section_style

    x_axis_section_style 参数允许您定义折线图中沿 x 轴的部分的视觉样式。

    • 支持的样式：
      • "dashed": 当您将 x_axis_section_style 设置为“dashed”时，沿 x 轴的剖面将使用虚线显示。
      • "normal": 相反，当 x_axis_section_style 设置为“正常”时，沿 x 轴的截面将使用实线显示。

    注意："normal"是默认样式。

  • y_axis_section_style

    与 x_axis_section_style 工作方式相同， 有关更多信息，请参阅 x_axis_section_style

  • x_axis_section_style_type

    x_axis_section_style_type 参数是一个包含两个整数值的元组，指定当 x_axis_section_style 设置为“dashed”时使用的破折号样式。
    例如:

    • 如果将 x_axis_section_style_type 设置为 (20, 10)，则意味着：
      • 每个破折号的宽度为 20 像素。
      • 破折号之间的间距为 10

    这些值确定用于表示沿 x 轴的部分的虚线或标记的视觉外观。通过调整这些值，您可以根据您的偏好或可视化要求自定义虚线部分的外观。

  • y_axis_section_style_type

    与 x_axis_section_style_type 工作相同， 请参阅 x_axis_section_style_type 了解更多信息

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_section_count=8, 
    y_axis_section_count=5, 
    x_axis_section_style="dashed", 
    x_axis_section_style_type=(20,10), 
    y_axis_section_style="dashed", 
    y_axis_section_style_type=(20,10), 
)

  • x_axis_point_spacing

    x_axis_point_spacing 参数允许您手动设置 x 轴上点之间的间距，通常以像素为单位测量。但是，如果您不手动设置该参数，则会根据 x_axis_values 的长度自动计算。
    注意："auto"是默认值。

    • 将特定值配置为 x_axis_point_spacing 后，您可以通过将其配置为"auto"来重置值以设置默认值。

    ``` python chart.configure( x_axis_point_spacing="auto" ) ``` 
    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_point_spacing="auto" 
)

    x_axis_point_spacing 参数是根据 x_axis_values 元组的长度自动计算的。这意味着 x 轴上点之间的间距是通过将折线图的宽度除以 x_axis_values 列表的长度来确定的。

    当您将 x_axis_point_spacing 参数设置为特定值（例如 40）时，这意味着您已手动将 x 轴上的点之间的间距指定为 40 个单位（例如像素）。在这种情况下，无论 x_axis_values 元组的长度如何，折线图都将在 x 轴上的每个点之间使用用户定义的 40 个单位的间距。

    chart = ctkchart.CTkLineChart(
    master=any_widget, 
    x_axis_point_spacing=40 
)

CTkLine

  • color

    指的是线条的颜色。

  • size

    指线条的尺寸（粗细）。
    注：1 为默认尺寸 

    line = ctkchart.CTkLine(
    master=chart, 
    color="#30ACC7", 
    size=5 
)

  • style

    style 参数允许您定义线条的视觉样式。

    • 支持的样式：
      • "dashed": 当样式设置为"dashed"时，折线条显示为虚线。
      • "dotted": 当样式设置为"dotted"时，折线显示为点虚线。
      • "normal": 当样式设置为"normal"时，线条显示为实线。

    注意："normal"是默认样式。

    line = ctkchart.CTkLine(
    master=chart, 
    line_style="dashed" 
)

  • style_type

    style_type 参数是一个包含两个整数值的元组，指定样式设置为"dashed"或"dotted"时使用的破折号和点的样式。

    例如:

    • 如果将 style_type 设置为 (20, 10)，则意味着：
      • 每个破折号的宽度或每个点的大小为 20 像素。
      • 破折号或点之间的间距为 10 个像素。

    注意 在"dotted"风格下 , size 参数无关紧要，因为点的大小是由 style_type 元组确定的固定大小。
    注意 在"normal"风格下，style_type 参数无效。

    line = ctkchart.CTkLine(
    master=chart, 
    line_style="dashed", 
    line_style_type=(10,2) 
)

  • point_highlight

    point_highlight 参数用于控制点高亮。

    • 支持的值：
      • "enabled": 启用点高亮显示。
      • "disabled": 禁用点高亮显示。

  • point_highlight_size

    point_highlight_size 用于设置高亮点的大小。

  • point_highlight_color

    高亮点的颜色。

    line = ctkchart.CTkLine(
    master=chart, 
    point_highlight="enabled", 
    point_highlight_color="#80CCFF", 
    point_highlight_size=8 
)

  • fill

    fill 参数用于控制是否启用或禁用行填充。

    • 支持的值：
      • "enabled": 启用线条填充。
      • "disabled": 禁用线条填充。

  • fill_color

    fill_color 参数用于指定填充的颜色。

    line = ctkchart.CTkLine(
    master=chart, 
    fill="enabled", 
    fill_color="#5D6DB6" 
)

动态颜色变化

对于 ctkchart 中涉及颜色的每个参数，有两种写法:

  • 代表颜色的单个字符串。
  • 两个字符串的元组，其中第一个字符串表示浅色主题的颜色，第二个字符串表示深色主题的颜色。

回到顶部 | 使用指南 | 参数说明 | 查看新功能

例子

回到顶部 | 使用指南 | 例子 | 参数说明

新的变化

链接

PyPi.org : ctkchart

GitHub.com : ctkchart

翻译贡献

翻译支持 : 有语

Translation by : youyu