pl-sketch元件¶
通过手绘或拖放来绘制曲线和其他数学对象（例如点、渐近线、多边形）。可以使用数学标准对绘图进行自动评分。一些标准示例是：
- 预期的点数或渐近线是否标记在正确的位置？
- 草图函数是否接近参考函数？
- 所描绘的函数总是单调递增吗？
- 画布的预期区域是否被覆盖（被多边形覆盖）？
请注意，此元素的设计重点是可以自动分级的数学曲线草图。对于更通用的手动分级工程图，请考虑使用 pl-excalidraw。对于不包含曲线的自动分级绘图，请考虑使用 pl-drawing。
样品元素¶
一个简单的问题，包含一种绘图工具、一种评分标准和一个示例解决方案：
<pl-sketch answers-name="simple-sketch" x-range="-5,5" y-range="-5,5">
<pl-sketch-tool id="fd" type="free-draw"></pl-sketch-tool>
<pl-sketch-grade type="match-function" tool-id="fd" function="x**2"></pl-sketch-grade>
<pl-sketch-solution tool-id="fd" function="x**2"></pl-sketch-solution>
</pl-sketch>
请注意，评分和解决方案元素引用相同的工具。 pl-sketch-grade 元素用于分级，而 pl-sketch-solution 元素用于渲染示例解决方案。
一个更完整的示例，结合了多种工具、初始图纸和几个分级标准：
<pl-sketch answers-name="sketch-example" x-range="-1,2" y-range="-1,5">
<pl-sketch-tool id="fd" type="free-draw"></pl-sketch-tool>
<pl-sketch-tool id="hl" type="horizontal-line"></pl-sketch-tool>
<pl-sketch-tool id="pt" type="point" read-only="true"></pl-sketch-tool>
<pl-sketch-initial tool-id="pt" coordinates="(-1,0.5)"></pl-sketch-initial>
<pl-sketch-initial tool-id="pt" coordinates="(0,1)"></pl-sketch-initial>
<pl-sketch-initial tool-id="pt" coordinates="(1,2)"></pl-sketch-initial>
<pl-sketch-initial tool-id="pt" coordinates="(2,4)"></pl-sketch-initial>
<pl-sketch-grade type="match" tool-id="hl" y="0"></pl-sketch-grade>
<pl-sketch-grade type="count" tool-id="hl" count="1"></pl-sketch-grade>
<pl-sketch-grade type="match-function" tool-id="fd" function="2**x"></pl-sketch-grade>
<pl-sketch-solution tool-id="fd" function="2**x"></pl-sketch-solution>
<pl-sketch-solution tool-id="hl" coordinates="0"></pl-sketch-solution>
</pl-sketch>
定制¶
| 属性 | 类型 | 默认 | 描述 |
|---|---|---|---|
answers-name |
字符串 | - | 用于存储数据的变量名称。请注意，该属性在问题中必须是唯一的，即该属性的值不应在问题中重复。 |
weight |
整数 | 1 | 计算元素的加权平均分数时使用的权重。 |
x-range |
字符串 | "-5,5" |
画布的 x 范围作为逗号分隔的数字对。在此范围周围添加 10 像素宽、未分级的边距。 |
y-range |
字符串 | "-5,5" |
画布的 y 范围作为逗号分隔的数字对。在此范围周围添加 10 像素宽、未分级的边距。 |
width |
整数 | 800 | 画布的显示宽度（以像素为单位）。请注意，该元素不响应，因此自定义宽度可能会导致显示问题，应谨慎使用。 |
height |
整数 | 450 | 450显示画布的高度（以像素为单位）。 |
read-only |
布尔 | 假 | 如果设置为 true，则图形不可编辑，并且顶部工具栏将被删除。此设置可以与 pl-sketch-initial（见下文）结合使用，将绘图渲染为静态问题材料。 |
overlay-solution |
布尔 | 真实 | 如果设置为 true，一旦问题答案揭晓，示例解决方案（通过 pl-sketch-solution 标签定义）就会与学生提交的内容重叠，以便更轻松地进行比较。 |
enforce-bounds |
布尔 | 假 | 如果设置为 true，则无法将对象拖过画布边缘。 |
allow-blank |
布尔 | 假 | 即使图表是空的，也允许对其进行评分。如果初始画布不为空并且在未进行任何更改的情况下提交，则它不会被视为空白，并且始终被视为有效提交。 |
上面的自定义是适用于整个草图画布的常规设置。请注意，某些设置（例如网格线和轴标签）是自动确定的，当前无法自定义。
要设置元素并自定义分级，可以在主元素内嵌套四种类型的元素：
pl-sketch-tool元素定义用于在画布内创建草图的绘图工具。pl-sketch-grade元素定义学生提交的评分标准。标准通常是指一种或多种特定的绘图工具。pl-sketch-initial元素定义画布的初始状态，使用特定工具绘制。pl-sketch-solution元素定义了示例解决方案，一旦答案揭晓，该示例解决方案就可以与学生提交的内容重叠。
使用 pl-sketch-tool 定义绘图工具¶
每个绘图工具元素代表一种可以在画布上绘制的对象。每个工具在元素的工具栏中都有一个按钮（除非设置了 read-only="true"）。工具具有定义其绘图行为和默认设置的通用类型（例如线、点）。可以创建并单独定制多个相同类型的工具，例如，允许学生在同一画布上绘制多个函数，或标记函数的不同类型的极值。
工具按定义顺序呈现。这意味着，例如，点应该定义在线之后，以出现在线之上。我们还建议在其他工具之前定义只读工具，以便它们不会干扰拖放交互。
请注意，除 type 和 id 之外的所有属性都是可选的，但默认值（除了 read-only 和 helper，默认为 false）取决于工具类型。下面单独列出了每种工具类型的默认设置。
| 参数 | 类型 | 适用于工具类型 | 描述 |
|---|---|---|---|
type |
字符串 | - | 工具类型（见下文） |
id |
字符串 | 全部 | pl-sketch-grade 和 pl-sketch-initial 元素中引用的工具的唯一名称。 |
label |
字符串 | 全部 | 工具栏中工具的标签。 |
read-only |
布尔 | 全部 | 如果设置为 true，学生将无法使用此工具，并且它不会出现在工具栏中。仅当定义了画布的初始状态时才可用。 |
limit |
整数 | 全部 | 使用此工具可以创建的绘图的最大数量。请注意，该限制不会影响样条线或多段线的可能线段数。 |
helper |
布尔 | 全部 | 如果设置为 true，该工具将显示在单独的“帮助”工具下拉列表中，这些工具仅用于在绘图过程中为学生提供支持。 |
group |
字符串 | 全部 | 该工具所属组的标签。分配给同一组标签的所有工具将显示在工具栏中的同一下拉列表中。 |
color |
字符串 | 全部 | 为工具绘制颜色。 |
dash-style |
字符串："solid"、"dashed"、"longdashed"、"dotted" 或 "dashdotted" |
直线、水平线、垂直线、折线、多边形 | 绘制线条的虚线样式。 |
direction-constraint |
字符串："none"、"horizontal" 或 "vertical" |
线 | 绘制线条方向的约束。 |
length-constraint |
浮动 | 线 | 如果不是0，则绘制线条的最大长度（在画布的内部坐标系中）。 |
arrowhead |
整数 | 线 | 如果不是 0，则自动插入到线条末端的箭头的大小（以像素为单位）。 |
size |
整数 | 点 | 绘制点的直径（以像素为单位）。 |
hollow |
布尔 | 点 | 点是绘制空心 (true) 还是填充 (false)。 |
fill-color |
字符串 | 多边形 | 绘制多边形的填充颜色。 |
opacity |
浮动 | 多边形 | 填充绘制多边形的不透明度（0 到 1 之间）。 |
该元素支持以下工具类型，默认设置如下：
free-draw¶
使用拖放绘制任何形状的线条。绘制后线条会稍微平滑，可以移动和删除，但绘制后无法编辑。
默认值：
id="fd" label="Function f(x)" color="blue"
point¶
通过单击画布中的特定位置来放置点。
默认值：
id="pt" label="Point" color="black" size="15"
horizontal-line¶
跨越整个画布的水平线（有效标记 y 坐标）。
默认值：
id="hl" label="Horizontal Line" color="dimgray" dash-style="dashdotted"
vertical-line¶
跨越整个画布的垂直线（有效标记 x 坐标）。
默认值：
id="vl" label="Vertical Line" color="dimgray" dash-style="dashdotted"
line¶
可以在两点之间绘制直线。可选约束可以限制长度/方向，可选箭头可以区分两个端点。
默认值：
id="line" label="Line" color="red" dash-style="solid" length-constraint="0" arrowhead="0"
polyline¶
复杂的线条，每条线条都由直线段组成。每个线段都通过另一个连接点来延伸线。按“Enter”或切换工具即可完成一行。线完成后可以移动点。
默认值：
id="pline" label="Function f(x)" color="orange"
spline¶
复杂线，每条线由多个线段组成。各段弯曲以形成整体线条。每个线段都通过另一个连接点来延伸线。按“Enter”或切换工具即可完成一行。线完成后可以移动点。
默认值：
id="sp" label="Function f(x)" color="purple"
polygon¶
多边形形状，每个形状由多个端点相连的线段组成。每个线段都通过另一个连接点延伸线，并自动插入端点的最终连接器。多边形的面积可以被涂上阴影。按“Enter”按钮或切换工具完成多边形。线完成后可以移动点。
默认值：
id="pg" label="Polygon" color="mediumseagreen" fill-color="mediumseagreen" opacity="0.5"
使用 pl-sketch-initial 和 pl-sketch-solution 添加初始图和解决方案图¶
对于只读元素和可由学生编辑的元素，可以将初始图和解决方案图添加到画布中。当问题最初在问题面板中呈现时，会出现初始绘图，而解决方案绘图会出现在解决方案面板中，以显示可能的示例解决方案。请注意，无法从分级标准推断出示例解决方案，因为该标准可能允许一系列可能的解决方案。
初始图和解决方案图是指确定其类型和样式的工具。对于初始绘图，如果工具设置了 read-only="true"，则它不会出现在工具栏中，并且添加的对象是固定的（例如，作为需要注释的给定函数）。否则，学生可以像编辑自己的绘图一样编辑对象。
以下属性适用于初始绘图和解决方案绘图：
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tool-id |
字符串 | - | 用于此绘图的工具 id (s)。 |
coordinates |
字符串 | - | 用于绘图的以逗号分隔的坐标列表（例如，-4.5、(1,2) 或 (1,2),(3,4)）。详情请参阅下文。 |
function |
字符串 | - | 用于绘制 spline 或 free-draw 对象的符号函数定义（见下文）。只能使用 coordinates 和 function 之一。 |
x-range |
字符串 | "," |
函数定义应绘制为逗号分隔的数字对的间隔，例如"-3,1.5"。仅在使用 function 时适用。范围的开始和/或结束可以为空白（例如，"-3," 或 ",-3"）以延伸到画布的边缘。 |
请注意，预期的坐标数量和解释取决于所引用工具的类型。 vertical-line 和 horizontal-line 工具仅需要单个坐标（x 或 y）。 point 工具需要逗号分隔的坐标对 (x,y)，而 line 需要 2 对 ((x1,y1),(x2,y2))，复杂直线工具或 polygon 需要 2 个或更多坐标对来表示由直线连接的点。多个标签可以引用同一工具来创建独立的绘图（例如，多个点或断开的线）。
使用 pl-sketch-initial 和 pl-sketch-solution 渲染符号函数¶
除了绘制单独的坐标之外，pl-sketch-initial 和 pl-sketch-solution 还支持渲染基于给定符号定义的函数。函数只能使用 spline 或 free-draw 类型的工具来呈现，并在发送到客户端之前转换为一系列行片段，因此符号定义不会向学生透露。
有关支持哪些类型的符号表达式的详细信息，请参阅下面的符号函数定义 部分。请注意，函数被渲染为一条连续线，因此对于非连续函数，可能需要将它们分成多个连续间隔以避免视觉伪影。例如：
<pl-sketch-initial tool-id="fd" function="1/x**3"></pl-sketch-initial>
应定义为：
<pl-sketch-initial tool-id="fd" function="1/x**3" x-range="-5,0"></pl-sketch-initial>
<pl-sketch-initial tool-id="fd" function="1/x**3" x-range="0,5"></pl-sketch-initial>
以避免垂直渐近线的左侧和右侧被连接。
使用 pl-sketch-grade 定义评分标准¶
每个评分标准元素代表一个评分检查，用于确定学生绘图的分数。草图元素的部分分数计算为所有评分标准的加权平均值。
与工具类似，每个评分标准都有一个通用类型（例如，计数、匹配），表示评分期间执行的检查类型。可以自定义标准以仅检查特定工具或范围，并分阶段要求在应用之前通过先决条件检查。
以下属性可用于自定义任何评分标准，与执行的检查类型无关：
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
type |
字符串 | - | 按评分标准执行的检查类型（见下文） |
tool-id |
字符串 | - | 工具 (s) 的一个或多个以逗号分隔的 id 将按此分级标准进行检查。 |
weight |
整数 | 1 | 计算元素部分分数时评分标准结果的权重。 |
x-range |
字符串 | ","（整个画布） |
应应用标准的 x 轴间隔，作为逗号分隔的数字对，例如"-3,1.5"。范围的开始和/或结束可以为空白（例如，"-3," 或 ",-3"）以延伸到画布的边缘。 |
feedback |
字符串 | "" |
如果评分检查失败，将向学生显示消息。如果设置为 ""，则反馈默认为取决于评分标准的通用消息。 |
tolerance |
整数 | （取决于支票类型） | 学生提交的内容可能偏离标准的容忍范围。对于大多数检查，容差是最大像素距离，但确切的定义和默认值取决于执行的检查类型。 |
stage |
整数 (optional) | 0 | 应用此标准的阶段（见下文）。始终应用默认阶段 0 的条件，即使其他条件使用自定义阶段也是如此。 |
debug |
布尔 | 假 | 如果设置为 true，反馈将显示有关未满足评分标准的原因的其他定量详细信息。这对于问题测试/调整很有用。 |
支持的评分类型¶
请注意，free-draw/polyline/spline 绘图被视为数学函数，因此每个 x 坐标最多可以有一个 y 值。如果在同一 x 坐标处绘制了多个值，则仅考虑第一个值进行评分。其他工具（例如 polygon、point 和 line）不会以这种方式处理，并且整个形状都会被考虑用于分级目的。
count¶
将使用指定工具(s)绘制的所有对象的总数与参考值进行比较。
支持的工具类型： 所有
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
count |
整数 | - | 用于检查的引用计数。 |
mode |
字符串 | "exact" |
"exact"、"at-least" 或 "at-most" 之一。 |
tolerance |
整数 | 15 | 15仅当设置了 x-range 时才适用；为 x 范围两端添加/删除的基于像素的边距（取决于 mode）。对于所有模式，x-range 内的计数或应用公差裕度后的计数都需要正确。 |
match¶
检查使用指定工具绘制的任何对象是否与参考坐标或点匹配（接触或相交）。该检查不支持x-range。
支持的工具类型： 所有
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
x |
浮动 | - | 参考 x 坐标。必须至少定义 x 或 y 之一。 |
y |
浮动 | - | 参考 y 坐标。必须至少定义 x 或 y 之一。 |
tolerance |
整数 | 15 | 15参考点和最近绘制点之间允许的像素距离。 |
endpoint |
字符串 | - | 仅适用于 line 刀具类型。哪个端点（"start"、"end" 或 "either"）应与参考匹配。 |
defined-in¶
检查使用指定工具组合绘制的所有对象是否覆盖参考 x 间隔的整个范围。
支持的工具类型： 除 horizontal-line、vertical-line 和 point 之外的所有工具类型
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 20 | 允许正确答案跳过的 x 间隔（以像素为单位）的部分。 |
undefined-in¶
检查使用指定工具组合绘制的对象是否不存在于参考 x 间隔中的任何位置。
支持的工具类型： 除 horizontal-line 之外的所有工具类型
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 20 | 允许正确答案覆盖的 x 间隔部分（以像素为单位）。 |
less-than¶
检查使用指定工具绘制的所有对象是否始终位于参考坐标或函数下方。只能设置 y 或 function。
支持的工具类型： 除 vertical-line 之外的所有工具类型
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
y |
浮动 | - | 参考 y 坐标。 |
function |
字符串 | - | 参考函数（参见符号函数定义）。 |
tolerance |
整数 | 15 | 15绘制对象允许达到参考上方的允许像素距离。 |
xy-flip |
布尔 | 假 | 如果是 true，则翻转 x 轴和 y 轴（详细信息见下文）。当 true 时，less-than 应解释为“左侧”，并指的是 x 坐标而不是 y。 |
y-range |
字符串 | - | 当 xy-flip 为 true 时，替换 x-range。 |
greater-than¶
检查使用指定工具绘制的所有对象是否始终位于参考坐标或函数上方。只能设置 y 或 function。
支持的工具类型： 除 vertical-line 之外的所有工具类型
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
y |
浮动 | - | 参考 y 坐标。 |
function |
字符串 | - | 参考函数（参见符号函数定义）。 |
tolerance |
整数 | 15 | 15绘制对象允许达到参考以下的允许像素距离。 |
xy-flip |
布尔 | 假 | 如果是 true，则翻转 x 轴和 y 轴（详细信息见下文）。当 true 时，greater-than 应解释为“右侧”，并指的是 x 坐标而不是 y。 |
y-range |
字符串 | - | 当 xy-flip 为 true 时，替换 x-range。 |
match-function¶
检查所有绘制的对象是否接近参考函数。
支持的工具类型： free-draw、point、polyline、spline
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
function |
字符串 | - | 参考函数（参见符号函数定义）。 |
allow-undefined |
布尔 | 假 | 如果是 false，则函数的整个域（具有一定的容差）必须被对象覆盖；否则，间隙将被忽略。 |
tolerance |
整数 | 15 | 15绘制对象允许偏离参考的允许像素距离。 |
xy-flip |
布尔 | 假 | 如果是 true，则翻转 x 轴和 y 轴（详细信息见下文）。 |
y-range |
字符串 | - | 当 xy-flip 为 true 时，替换 x-range。 |
monot-increasing¶
检查绘制的函数是否单调递增。通过将每个分级对象单独划分为 100 个大小相等的区间并比较它们的终点来执行此检查。
支持的工具类型： free-draw、line、polyline、spline
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 5 | 每个对象允许有多少段未定义或减少。 |
monot-decreasing¶
检查绘制的函数是否单调递减。通过将每个分级对象单独划分为 100 个大小相等的区间并比较它们的终点来执行此检查。
支持的工具类型： free-draw、line、polyline、spline
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 5 | 每个对象允许有多少段未定义或增加。 |
concave-up¶
检查绘制的函数是否凹且面朝上。通过将每个分级对象单独划分为 100 个大小相等的间隔并检查每个间隔的形状来执行此检查。请注意，line 和 polyline 对象不被视为凹面，因此它们始终不符合此标准。
支持的工具类型： free-draw、line、polyline、spline
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 10 | 10每个对象允许有多少个段是未定义的或不是凹面/朝上的。 |
concave-down¶
检查绘制的函数是否凹且朝下。通过将每个分级对象单独划分为 100 个大小相等的间隔并检查每个间隔的形状来执行此检查。请注意，line 和 polyline 对象不被视为凹面，因此它们始终不符合此标准。
支持的工具类型： free-draw、line、polyline、spline
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
tolerance |
整数 | 10 | 10每个对象允许有多少个段是未定义的或不是凹面/朝下的。 |
符号函数定义¶
上面的一些分级检查允许使用符号函数定义作为参考。这些在 function 属性中作为字符串提供，并且必须使用 Python 表达式语法。它们必须使用 x 作为输入变量名称。支持基本算术运算（+、-、*、/ 和 ** 用于求幂）、括号、常量 e 和 pi 以及以下 Python 函数调用： abs、sign、sqrt、log、sin、cos、tan、sinh、cosh、 tanh、asin、acos、atan、atan2、asinh、acosh 和 atanh。例如，可以写：function="x**2 + 2*x - sin(pi*x)"。
如果将 xy-flip 属性设置为 true 作为评分标准，则提供的函数 function 将被视为曲线 x = f(y)。此特殊用途标志可用于对垂直定义的曲线进行分级，例如 x = y**2，但应谨慎使用，因为它还会更改其设置的分级检查的语义。最重要的是，如果 xy-flip 是 true，则 less-than 和 greater-than 应分别解释为“左侧”和“右侧”，并指的是 x 坐标而不是 y 坐标。应使用属性 y-range 代替 x-range，并且不支持 less-than 和 greater-than 标准的属性 y。 The function attribute should also be defined with respect to y as the input variable.
例如，可以使用属性为xy-flip="true" type="less-than" function="y**2"的标签来测试学生提交的绘图是否位于曲线x = y**2的左侧。有关更多示例，请参阅示例课程。
可选的分级阶段¶
默认情况下，所有评分标准都被视为完全独立的。然而，在某些情况下，可能希望评分标准仅在不同的标准已经通过的情况下才奖励分数。例如，人们可能不想因为_未_定义某个范围内的函数（通过 undefined-in 检查）而给学生奖励分数，除非他们也在正确的范围内定义了该函数（通过 defined-in 检查）。为了强制执行此类依赖性，可以为条件分配数字 stage 属性。
If any grading criterion with a lower stage number than another criterion fails, the one with the higher stage number automatically fails as well.任何没有分配阶段的剩余标准都会受到检查，并且不需要通过任何阶段检查。
请注意，在确定可达到的分数时仍会考虑所有标准，除非它们是使用 weight="0" 定义的。对于前面的示例，defined-in 标签可以分配为 stage="1"，undefined-in 标签可以分配为 stage="2"，因此学生除非在正确的范围内定义函数，否则不会获得任何分数。
无障碍¶
由于该元素的高度图形化性质，目前没有可行的键盘控制或合理的屏幕阅读器交互可用。为了满足一些可访问性需求，有必要提供草图问题的替代版本，例如允许学生给出文字描述而不是绘图。
示例实现¶
- [元素/草图]