Oppia 扩展系统（Extensions）完全解析：interactions、objects、RTE 组件与可视化插件的架构与实践

教育后端前端【免费下载链接】oppiaA free, online learning platform to make quality education accessible for all.项目地址https://gitcode.com/gh_mirrors/op/oppia点击查看免费下载Oppia 是一个免费、开放的在线学习平台其课程内容Explorations的交互体验高度依赖一套插件化的扩展体系。本文以仓库 extensions/README.md 为主线系统讲解 Oppiaextensions目录中 actions、answer_summarizers、ckeditor_plugins、interactions、objects、rich_text_components、value_generators、visualizations 八大扩展模块的职责、源码结构与扩展开发方法。读完本文你将掌握每个扩展模块的目录约定、Python/TypeScript 双端实现模式以及如何为 Oppia 新增一个交互或富文本组件。扩展系统总览一份目录八类插件extensions/README.md 明确说明该目录集中存放 Oppia 代码库中各类扩展与插件的前端与后端代码。它并非单一功能模块而是围绕如何让课程内容可交互、可编辑、可统计这一目标组织的八类插件集合目录职责技术形态actions用户在 Oppia 网站上的各类行为action的领域类定义Python 后端配置answer_summarizers答案汇总器answer summarizer的模型定义Python 后端计算模型ckeditor_pluginsCKEditor RTE 中使用的插件JavaScript 前端插件interactionsOppia 网站支持的交互互动组件的前后端代码Python TypeScriptobjects各类类型化编辑器布尔编辑器、文件路径编辑器等的前后端代码Python TypeScriptrich_text_componentsOppia RTE 支持的富文本组件的前后端代码Python TypeScriptvalue_generatorsOppia 中使用的值生成器代码Python TypeScriptvisualizationsOppia 中使用的答案可视化代码Python TypeScript除上述八类之外目录中还包含三个基础设施文件extensions/domain.py 定义了跨扩展共享的CustomizationArgSpec等值对象extensions/extensions.module.ts 是扩展组件的前端 Angular 模块入口extensions/domain_test.py 提供对应的后端测试。双端并行的模块组织惯例从目录结构看除ckeditor_plugins外每个扩展模块都遵循后端配置 前端实现的对称布局后端用 Python 类声明元数据名称、描述、自定义参数规格、规则描述等前端用 TypeScript Angular 组件渲染交互界面。以交互模块为例BaseInteraction类extensions/interactions/base.py是所有交互的后端基类注释中明确要求每个交互附带一张 178 × 146 像素的缩略图供交互选择器interaction selector展示——这正是双端协作的一个缩影。actions学习者行为Learner Action的领域建模actions模块负责定义用户在 Oppia 上发生的行为的领域类。当前仓库包含三个具体行为与一个基类extensions/actions/AnswerSubmit记录学习者提交答案的行为extensions/actions/ExplorationQuit记录学习者中途退出探索的行为extensions/actions/ExplorationStart记录学习者开始探索的行为。BaseLearnerActionSpec 基类所有行为类都继承自 extensions/actions/base.py 中的BaseLearnerActionSpec。该基类被明确标注为不可由用户编辑只应提供 getter 方法其核心是一个_customization_arg_specs类属性列表每个规格包含 name、description、schema、default_value 四个字段并通过customization_arg_specs属性将其转换为domain.CustomizationArgSpec值对象。to_dict()方法负责输出仅含默认值的字典表示。AnswerSubmit 的规格定义示例以 AnswerSubmit/AnswerSubmit.py 为例它声明了六个自定义参数规格参数名说明类型默认值state_name当前状态名unicodedest_state_name目标状态名unicodeinteraction_id交互 IDunicodesubmitted_answer提交的答案unicodefeedback对提交答案的反馈unicodetime_spent_state_in_msecs在该状态停留的毫秒数int0这些规格模式与交互、富文本组件中的自定义参数规格完全一致体现了 Oppia 扩展体系中自定义参数规格customization arg specs这一贯穿始终的统一抽象。answer_summarizers答案汇总计算模型answer_summarizers模块extensions/answer_summarizers/models.py提供对已记录的状态答案state answers执行统计计算的模型。其模块文档给出了开发者接入方式的关键说明要为某个交互INTERACTION_NAME指定计算需编辑extensions.interactions.INTERACTION_NAME.answer_visualizations列表每个可视化条目是一个包含id、options、calculation_id三个键的字典例如answer_visualizations [{ id: SortedTiles, options: { use_percentages: True, header: Pretty Tiles!, }, calculation_id: AnswerFrequencies, }]计算模型的分类体系该模块定义了两类重要常量CLASSIFICATION_CATEGORIES包含显式分类EXPLICIT、训练数据分类TRAINING_DATA、统计分类STATISTICAL与默认结果分类DEFAULT_OUTCOME四类UNRESOLVED_ANSWER_CLASSIFICATION_CATEGORIES仅包含统计分类与默认结果分类用于界定未解决答案。所有计算类继承自BaseCalculation其id属性直接取类名calculate_from_state_answers_dict()抽象方法需在子类中实现且均在 MapReduce 批处理任务上下文中运行。仓库内置了六种计算实现AnswerFrequencies统计每个答案的提交次数返回{answer: ..., frequency: ...}列表Top5AnswerFrequencies/Top10AnswerFrequencies分别只保留频次最高的前 5 / 前 10 个答案FrequencyCommonlySubmittedElements面向集合型答案如SetOfUnicodeString统计各独立元素的频次要求答案必须可迭代否则抛出异常TopAnswersByCategorization按分类类别分组统计答案频次TopNUnresolvedAnswersByFrequency过滤出未解决答案并按其频次降序排列上限由 core/feconf.py 中的TOP_UNRESOLVED_ANSWERS_LIMIT 20控制。这些计算统一以 core/domain/calculation_registry.py 中的注册表按类名查取并被可视化模块引用。ckeditor_pluginsCKEditor 富文本编辑器的扩展插件ckeditor_plugins模块存放 CKEditor RTE 使用的插件目前仓库只含一个pre插件extensions/ckeditor_plugins/pre/plugin.js其功能是让编辑者在富文本中插入pre预格式化文本块。该插件通过标准的CKEDITOR.plugins.add(pre, {...})API 注册包含一个styleCommand命令、工具栏按钮Pre置于 insert 工具栏以及按钮高亮状态同步逻辑配套图标位于pre/icons/目录。由此可以推断新增 RTE 插件的模式在 extensions/ckeditor_plugins 下新建目录、按 CKEditor 插件规范编写plugin.js并在编辑器配置中引用。interactions交互互动组件的前后端实现interactions是扩展体系中最庞大的模块当前包含 20 个交互AlgebraicExpressionInput、CodeRepl、Continue、DragAndDropSortInput、EndExploration、FractionInput、GraphInput、ImageClickInput、InteractiveMap、ItemSelectionInput、MathEquationInput、MultipleChoiceInput、MusicNotesInput、NumberWithUnits、NumericExpressionInput、NumericInput、PencilCodeEditor、RatioExpressionInput、SetInput、TextInput。此外模块根目录还有 interaction_specs.json、rule_templates.json、answer-defs.ts、rule-input-defs.ts、customization-args-defs.ts 等全局定义文件。BaseInteraction交互的身份档案每个交互的后端 Python 类继承 extensions/interactions/base.py 中的BaseInteraction并通过类属性声明一份完整的身份档案其中核心字段包括字段含义典型值name/description人类可读的名称与描述Text Inputdisplay_mode展示方式inline内嵌对话流或supplemental独立对象base.DISPLAY_MODE_INLINEis_terminal是否为终止型交互结束探索EndExploration为Trueis_linear是否只有唯一答案Continue为Trueis_trainable是否支持机器学习分类TextInput为Trueanswer_type接受的答案类型字符串NormalizedString_customization_arg_specs自定义参数规格列表见下文_answer_visualization_specs答案可视化规格列表见下文can_have_solution是否支持解题提示solution功能TextInput为Trueshow_generic_submit_button是否在导航区显示通用提交按钮TextInput为Truedisplay_mode的两种取值在 base.py 中定义为常量DISPLAY_MODE_INLINE与DISPLAY_MODE_SUPPLEMENTAL后者模式下若相邻两个状态使用相同交互 ID交互实例会被复用。自定义参数规格customization args交互的可配置项交互的编辑器侧配置能力来自_customization_arg_specs。以 TextInput/TextInput.py 为例它声明了三个自定义参数_customization_arg_specs [ { name: placeholder, description: Placeholder text (optional), schema: {type: custom, obj_type: SubtitledUnicode}, default_value: {content_id: None, unicode_str: }, }, { name: rows, description: Height (in rows), schema: { type: int, validators: [ {id: is_at_least, min_value: 1}, {id: is_at_most, max_value: 10}, ], }, default_value: 1, }, { name: catchMisspellings, description: Catch Misspellings (Detect if answer is misspelled ...), schema: {type: bool}, default_value: False, }, ]注意其中rows参数通过 schema 的validators约束取值范围为 110这是 Oppia 表单渲染引擎core/schema_utils.py在编辑器界面自动校验数据合法性的关键机制。文本注释还提示旧版本中曾有一个columns参数为兼容历史探索数据不要再复用该参数名。答案可视化规格与规则描述交互的_answer_visualization_specs把答案统计与展示方式绑定在一起。TextInput 配了两个FrequencyTable可视化第一个用Top10AnswerFrequencies计算展示 Top 10 答案第二个用TopNUnresolvedAnswersByFrequency展示未解决答案。前端通过 interactions/base-interaction-validation.service.ts 校验这些规格后端则在 base.py 的answer_visualizations属性中借助 core/domain/visualization_registry.py 按 ID 实例化可视化类。规则描述统一以 JSON 形式维护在 interaction_specs.json 中。以ImageClickInput为例其规则为IsInRegion: is in the region {{x|UnicodeString}}——{{参数名|对象类型}}占位符语法由get_rule_param_list()base.py解析从中提取规则参数及其extensions.objects.models中的对象类型从而支持通用的规则参数类型推断。一个交互的前端组成每个交互目录下同时包含 Angular 组件与配套测试。以 TextInput 为例TextInput.ts 汇总 require 了以下前端依赖text-input-rules.service.ts规则判定服务text-input-validation.service.ts自定义参数合法性校验服务oppia-interactive-text-input.component.ts学习者侧的交互组件oppia-response-text-input.component.ts学习者作答后的完整回答展示组件oppia-short-response-text-input.component.ts回答的短摘要展示组件。对应的 HTML 模板与 spec 测试位于 extensions/interactions/TextInput/directives 目录。这五件套交互组件、回答组件、短回答组件、规则服务、校验服务是 Oppia 交互的前端标准结构。objects类型化编辑器与领域对象objects模块承载 Oppia 中各类类型化对象的定义与对应编辑器组件。后端核心是 extensions/objects/models/objects.py其中定义了UnicodeString、Html、Filepath、SanitizedUrl、MathExpressionContent、ListOfTabs、SvgFilename、Int、Boolean、SkillSelector等对象类每个类都提供normalize()方法做数据规范化。这些对象类是交互答案类型、富文本组件参数、规则参数校验的共同基石——例如 rich_text_components/components.py 中维护了一张从对象类型名到对象类的映射表正是复用这套模型。objects模块还包括extensions/objects/object_defaults.json各对象的默认值定义extensions/objects/object-components.module.ts对象编辑器组件的 Angular 模块extensions/objects/templates各类编辑器布尔编辑器、文件路径编辑器、坐标编辑器等的组件模板。rich_text_componentsRTE 富文本组件rich_text_components模块定义 Oppia 富文本编辑器RTE中可插入的组件目前包含八个组件Collapsible折叠块、Image图片、Link链接、Math数学公式、Skillreview技能回顾、Tabs选项卡、Video视频、Workedexample例题讲解。BaseRteComponent 与参数校验后端基类 extensions/rich_text_components/components.py 的BaseRteComponent通过类方法validate()校验组件参数它从 assets/rich_text_components_definitions.ts由feconf.RTE_EXTENSIONS_DEFINITIONS_PATH指定见 core/feconf.py读取各组件的customization_arg_specs将每个参数的 schema 类型映射到 objects 对象类后调用normalize()校验并严格核对参数集合发现缺失或多余属性即抛出utils.ValidationError。新增富文本组件的标准步骤extensions/rich_text_components/README.md 给出了新增组件的三步流程在extensions/rich_text_components/下新建目录并放置全部文件后端 Python 类、前端组件与模板在assets/rich_text_components_definitions.ts中为该组件新增一条 JSON 记录含名称、描述、customization_arg_specs 等在core/templates/components/ck-editor-helpers/rich-text-components.template.html中加入对应的脚本导入使组件出现在 CKEditor 工具栏中。同时core/templates/components/ck-editor-helpers 目录下的其他文件如复制工具栏组件共同构成了 RTE 的编辑辅助设施。前端侧extensions/rich_text_components/rte-output-display.component.ts 负责在探索播放时渲染这些组件extensions/rich_text_components/richTextComponentsRequires.ts 汇总各组件的前端依赖。value_generators参数值生成器value_generators模块提供值生成器——在探索运行时根据上下文参数动态生成自定义参数值的工具。后端模型位于 extensions/value_generators/models/generators.py包含两个生成器均继承 core/domain/value_generators_domain.py 的BaseValueGeneratorCopier通过copy.deepcopy(value)原样复制输入值RandomSelector通过utils.get_random_choice(list_of_values)从输入列表中随机选取一个值。前端模板位于 extensions/value_generators/templates包括Copier.component.html、RandomSelector.component.html及对应的 Angular 组件copier.component.ts、random-selector.component.ts供探索编辑器在配置参数时选择复制或随机选取两种取值策略valueGeneratorsRequires.ts负责汇总前端依赖。visualizations学习者答案可视化visualizations模块实现对汇总后的学习者答案进行可视化展示后端定义在 extensions/visualizations/models.py前端为对应的 Angular 指令/组件。基类BaseVisualization接收三个关键参数calculation_id关联的答案汇总计算来自 answer_summarizers 模块options_dict可视化的选项配置addressed_info_is_supported是否支持已回答信息标记。其validate()方法会依次校验计算 ID 在 core/domain/calculation_registry.py 中真实存在、选项名与_OPTIONS_SPECS声明完全一致借助 core/schema_utils.py 做 schema 归一化、以及addressed_info_is_supported为布尔值。仓库内置四种可视化可视化前端文件说明ClickHexbinsoppia-visualization-click-hexbins.directive.ts在图片上以六边形分组叠加展示点击分布面向ImageClickInput这类点击型交互FrequencyTableoppia-visualization-frequency-table.directive.ts两列答案频次表格EnumeratedFrequencyTableoppia-visualization-enumerated-frequency-table.directive.ts带序号枚举的频次表格SortedTilesoppia-visualization-sorted-tiles.component.ts按频次排序的答案磁贴ClickHexbins的注释还解释了为何选择六边形分箱相比正方形网格六边形在平面密铺中拥有对称的最近邻关系覆盖效率高约 13%且视觉上对密度分布更少偏见。这类可视化正是通过BaseInteraction.answer_visualizations与各交互的_answer_visualization_specs绑定到具体交互上的。贯穿全局的统一抽象CustomizationArgSpec无论 actions、interactions 还是 rich_text_components都用同一套自定义参数规格抽象描述可配置项其值对象定义在 extensions/domain.pyclass CustomizationArgSpec: def __init__(self, name, description, schema, default_value) - None: self.name name self.description description self.schema schema self.default_value default_value def to_dict(self) - CustomizationArgSpecsDict: return { name: self.name, description: self.description, schema: self.schema, default_value: self.default_value, }domain.py同时定义了参数默认值允许的类型集合AllowedDefaultValueTypes涵盖字符串、浮点数、图结构GraphDict、图片区域ImageAndRegionDict、带字幕的 Unicode/HTML 以及它们的列表。CustomizationArgSpec的具体实例化方式有两种actions 与 interactions 的后端基类各自通过[domain.CustomizationArgSpec(**cas) for cas in self._customization_arg_specs]批量构造见 extensions/actions/base.py 与 extensions/interactions/base.py编辑器前端则以 JSON 形式消费同一份规格实现一处声明、双端可用。扩展开发实战以新增一个交互为例综合以上源码结构可以为 Oppia 新增一个交互梳理出完整开发路线该流程同样适用于新增富文本组件仅需将目标目录换成rich_text_components创建目录骨架在 extensions/interactions 下新建InteractionName/目录参考 TextInput 的标准结构编写后端 Python 类继承BaseInteractionextensions/interactions/base.py声明name、description、display_mode、answer_type、is_trainable、is_terminal、is_linear、can_have_solution、show_generic_submit_button等属性并通过_customization_arg_specs声明可配置参数注意利用 schemavalidators约束参数范围声明答案可视化在_answer_visualization_specs中组合id、options、calculation_id引用 extensions/answer_summarizers/models.py 的计算类定义规则描述在 interaction_specs.json 中登记规则描述与规则模板使用{{参数名|对象类型}}占位符语法编写前端组件实现交互组件、回答组件、短回答组件三个 Angular 组件及 HTML 模板并在InteractionName.ts汇总 require 依赖实现规则与校验服务提供interaction-name-rules.service.ts与interaction-name-validation.service.ts补充测试参照各模块的*_test.py与.spec.ts文件补齐后端单测与前端单元测试如 base_test.py、base-interaction-validation.service.spec.ts注册与构建确保交互被 extensions/interactions/interactions.module.ts 等模块聚合并满足BaseInteraction对缩略图178 × 146 像素等约定要求。结语Oppia 的扩展体系以extensions目录为枢纽用自定义参数规格统一描述配置、用答案汇总计算 可视化统一呈现统计、用Python 声明 TypeScript 渲染统一实现前后端形成了高度模块化、可测试、可组合的插件架构。开发者只要吃透 extensions/interactions/base.py 与 extensions/rich_text_components/components.py 两个基类即可按固定范式快速扩展新的交互与富文本组件而 extensions/domain.py、extensions/answer_summarizers/models.py、extensions/visualizations/models.py 则分别提供了跨扩展共享的值对象、统计计算与可视化展示能力。对于想要深入源码的读者建议从BaseInteraction、BaseRteComponent、BaseVisualization三个基类及其测试文件入手逐一对照各交互/组件的具体子类实现即可完整掌握这套扩展体系的设计全貌。赞分享教育后端前端【免费下载链接】oppiaA free, online learning platform to make quality education accessible for all.项目地址https://gitcode.com/gh_mirrors/op/oppia点击查看免费下载相关推荐Linera插件系统可扩展架构与自定义组件Linera插件系统可扩展架构与自定义组件 引言 在区块链应用开发中高效的数据索引和查询是构建复杂DApp去中心化应用的关键挑战。Linera协议通过其区块链Web3革命性x86模拟器FEX在ARM64 Linux上无缝运行Windows游戏和应用的终极指南革命性x86模拟器FEX在ARM64 Linux上无缝运行Windows游戏和应用的终极指南 FEX是一款革命性的x86和x86 64用户模式模拟器专门为AJIT编译虚拟化从零到物联网如何用Arduino ESP32避开新手最易踩的5个坑从零到物联网如何用Arduino ESP32避开新手最易踩的5个坑 你是否曾满怀热情地开始一个ESP32物联网项目却在环境配置阶段就碰壁明明按照教程一步嵌入式物联网驱动开发上一篇SilentPatchGTA III、罪恶都市、圣安地列斯在 Win10/11 上的兼容补丁不崩不卡下一篇如何 2 小时落地GB28181 国标视频监控平台的从 0 到 1 部署实录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考