ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

p5.js 友好错误系统(FES)完全指南:工作原理、多语言错误信息编写与性能关闭

p5.js 友好错误系统(FES)完全指南:工作原理、多语言错误信息编写与性能关闭 p5.js 友好错误系统FES完全指南工作原理、多语言错误信息编写与性能关闭【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.jsp5.js 的友好错误系统Friendly Error System简称 FES符号 是一个面向新手程序员的内置调试辅助机制它把浏览器控制台中晦涩的报错翻译成简单、友好、附带参考链接的中文/英文提示并自动检查函数参数是否写错。本文以 contributor_docs/zh-Hans/friendly_error_system.md 为骨架结合 src/friendly_errors 源码与 translations 多语言翻译文件系统讲解 FES 的定位、消息编写规范、i18next 翻译文件结构、底层错误生成/显示机制以及如何通过p5.disableFriendlyErrors关闭它。读完本文你既能以用户身份读懂并调优 p5.js 的报错也能以贡献者身份写出高质量的友好错误消息。概述FES 是什么友好错误系统FES旨在通过提供简单友好的错误信息帮助新手程序员。它通过在错误消息中添加替代描述和有用的参考链接补充而非替换浏览器控制台的错误消息。FES 将消息打印在控制台窗口中在 p5.js Web Editor 和浏览器的 JavaScript 控制台中都能看到。一个关键事实单个压缩文件版本的 p5p5.min.js不包含 FES。这是因为构建压缩版时会剔除友好错误相关的代码从而减小体积、提升性能。从源码看src/friendly_errors/fes_core.js 中通过typeof IS_MINIFIED ! undefined判断构建环境一旦处于压缩构建模式就把p5._friendlyError与p5._checkForUserDefinedFunctions直接置为空函数从根上跳过整套错误处理逻辑if (typeof IS_MINIFIED ! undefined) { p5._friendlyError p5._checkForUserDefinedFunctions () {}; }降低调试障碍FES 的设计理念工具的设计应该符合将使用它的人的需求。作为旨在降低调试障碍的工具FES 的设计也不例外。评估现有设计的最佳方法是直接听取使用 p5.js 的人们的意见。项目在 2021 年进行了社区调查以收集对友好错误的反馈和未来期望。社区成员的见解对贡献者很有帮助调查结果可以通过摘要漫画或完整报告查看21-22 FES 调查报告漫画21-22 FES 调查完整报告这一调查驱动的设计思路在代码层面也有呼应例如 src/friendly_errors/fes_core.js 中定义了拼写检查的 Levenshtein 编辑距离阈值EDIT_DIST_THRESHOLD 2用于判断用户是否把某个 p5 符号如HALF_PI、createCanvas拼错了——这正是基于新手常犯的拼写/大小写错误这一真实用户行为设计的。编写友好错误消息贡献者的入门路径如何通过编写和翻译错误消息来为 p5.js 库做出贡献FES 是 p5.js 国际化工作的一部分。所有 FES 消息的内容都通过基于 i18next 的translator()函数动态生成这种动态错误消息生成适用于所有语言包括 p5.js 的默认语言英语。也就是说即使是英文错误文本也不在源码中硬编码而是统一从翻译文件中取出后拼接。编写最佳实践FES 消息编写者应优先考虑降低理解错误消息的障碍增加调试过程的可访问性。这里总结自 Friendly Errors i18n Book这是一个公开项目可以通过单独的 repo 为其贡献了解你的受众不要对错误消息的受众做出假设尝试了解谁在使用我们的库以及他们如何使用它。保持语言包容性努力使错误消息友好——这对你意味着什么在您的语言中寻找可能的偏见和伤害遵守 p5.js 行为准则。尽量使用简单的句子考虑将句子分成较小的块以最大程度地利用 i18next 的插值功能。优先考虑跨文化沟通在不同语言之间提供出色的体验避免使用成语习语难以翻译且易产生歧义。逐步介绍技术概念一次只引入一个技术概念或术语保持技术写作的一致性尝试链接一个用简明实例编写的、面向初学者的外部资源。翻译文件的位置translator()基于 i18next从 src/core/internationalization.js 中导入在当前仓库结构中实际实现见 src/friendly_errors/fes.js 与 translations 目录。它通过从 JSON 翻译文件中查找文本数据来生成消息查找路径遵循如下约定translations/{{检测到的语言代码默认为en}}/translation.json示例如果检测到的浏览器语言环境是韩语语言标识符kotranslator()将从translations/ko/translation.json中读取翻译的文本块然后将文本块组合成最终消息。当前仓库的 translations 目录中已包含en、es、hi、ja、ko、zh六种语言的翻译文件。语言标识符还可以包含地区信息例如es-PE秘鲁的西班牙语从而支持同一语言在不同地区的差异化文案。翻译文件的结构translation.json采用 i18next 使用的 JSON 格式。翻译文件的基本格式是在花括号{}中使用双引号括起来的键和值消息{ key: value }例如p5.js 在控制台打印的 ASCII 标志就保存在这种格式中\n表示换行logo: _ \n /\\| |/\\ \n \\ / \n / , . \\ \n \\/|_|\\/ \n\ni18next 支持插值interpolation允许传入变量以动态生成消息。使用两个花括号{{}}设置变量的占位符greeting: 你好{{who}}这里键是greeting变量名是who。为了动态生成该消息需要传递一个值translator(greeting, { who: everyone });由translator生成的结果为你好everyonefes命名空间下的fileLoadError项演示了插值在实际错误消息中的应用。以 translations/zh/translation.json 中的fes.fileLoadError.image为例image: 似乎在加载图像时出现了问题。{{suggestion}}为了动态生成最终消息FES 将使用该键和预先生成的suggestion值调用translator()translator(fes.fileLoadError.image, { suggestion });从 translations/en/translation.json 可以看到完整的fes.fileLoadError家族image、font、json、strings、table、xml、bytes等不同类型资源各有专属文案而suggestion与large是公共片段分别给出检查文件路径 / 托管在线 / 运行本地服务器的建议和针对大文件的拆分建议。这种公共片段 类型专属片段的拆分组合正是把句子分成较小块以最大化利用插值这一最佳实践的直接体现。如何添加或修改翻译国际化文档 提供了逐步指南介绍如何添加和修改翻译文件。大致流程是在 translations 下对应语言目录的translation.json中按 i18next JSON 格式补充或修改fes命名空间下的键值对并遵循上述编写最佳实践然后通过测试验证消息渲染效果。理解 FES 的工作原理本节概述 FES 如何生成和显示消息关于 FES 函数的更详细信息可参阅 FES 参考 开发笔记 和 FES 贡献指南。概览p5.js 何时调用 FESp5.js 从多个位置调用 FES以处理不同的情况浏览器引发错误如语法错误、引用错误、类型错误用户代码调用 p5.js API 的函数如参数个数、类型不匹配其他用户可以从帮助消息中受益的自定义情况如文件加载失败、在顶层误用 p5 符号。FES 代码位置文档给出的核心组件位置是src/core/friendly_errors在当前仓库中实际对应 src/friendly_errors目录包含 7 个文件fes_core.js —— FES 核心含_friendlyError、fesErrorMonitor、拼写检查等fes.js —— 基于tl-utili18next 的轻量封装的FES日志类与多语言支持browser_errors.js —— 浏览器错误消息 → 错误类型的查找表errorTableparam_validator.js —— 基于 Zod 的参数校验器stacktrace.js —— 错误堆栈解析借用自 stacktrace.js 项目sketch_verifier.js、index.js —— 草图验证与模块入口。translator()使用的翻译文件位于 translations每种语言一个translation.json。FES 消息生成器以下函数主要负责捕获错误并生成 FES 消息_friendlyFileLoadError()捕获文件加载错误。在 src/io/files.js、src/image/loading_displaying.js、src/webgl/loading.js 等加载路径中可以看到loadJSON、loadImage、loadModel等函数在请求失败时调用它并传入错误类型编号与资源路径最终文案对应翻译文件中的fes.fileLoadError.*系列。_validateParameters()根据内联文档检查 p5.js 函数的输入参数。当前仓库中这一职责由 param_validator.js 承担它从 docs/parameterData.json 读取每个函数的重载签名例如background的[Number, Number, Number, Number?]用 Zod 动态生成校验 Schema 并缓存到schemaRegistry再通过findClosestSchema()找到与用户实参最接近的重载从而给出期望第几个参数是什么类型的精准提示校验器还通过p5.registerDecorator包裹p5.prototype方法并用_isUserCall标志跳过内部嵌套调用避免误报。_fesErrorMonitor()处理全局错误。它是注册在window上的error与unhandledrejection事件监听器见 src/friendly_errors/fes_core.js工作流程为先从事件对象提取Error兼容ErrorEvent、PromiseRejectionEvent解析堆栈并简化出friendlyStack若错误发生在库内部则直接忽略isInternal随后用 browser_errors.js 中的errorTable把浏览器原生报错归类——该表针对 Chrome / Firefox / Safari 的措辞差异为同一类错误维护了多条匹配模式例如not definedChrome、Cant find variableSafari、is not definedFirefox都映射到ReferenceError/NOTDEFINED。归类后再按SyntaxError、ReferenceError、TypeError分派到具体的友好文案并附带 MDN 等参考链接与堆栈位置。此外FES 还有两个值得了解的辅助能力均在 fes_core.js 中拼写检查handleMisspelling()当抛出ReferenceError且符号未定义时用 Wagner–Fischer 算法computeEditDistance计算该符号与所有公开 p5 符号的编辑距离阈值取min(2, errSym.length)命中后会提示您可能误写了xxx请更正为yyy若同时存在多个相近候选则逐行列出并附带参考文档链接。顶层误用检测helpForMisusedAtTopLevelCode()defineMisusedAtTopLevelCode()会惰性收集 p5 的公开符号按名称长度降序排列以保证优先报告更具体的符号例如HALF_PI而非PI当用户在setup()/draw()之外使用这些符号时给出请将其移入 setup() 函数的提示。FES 消息显示器fes_core.js中的_friendlyError()在控制台中打印生成的友好错误消息。它是一个可在 p5 任何地方调用的通用方法例如p5._friendlyError(translator(fes.globalErrors.type.notfunc, translationObj));从实现看src/friendly_errors/fes_core.js_friendlyError首先检查p5.disableFriendlyErrors随后交给p5._report()mapToReference()会根据函数名拼接 p5 官方参考文档链接形如https://p5js.org/reference/...load*系列函数除外最终由 fes.js 中的FES类负责输出。FES类封装了log/warn/error/info/debug五种控制台方法通过TL.tl模板标签做实时翻译默认在消息前加上 p5.js says:前缀可用prefix: false关闭并支持red()、white()、bgBlack()、underline()等样式函数为关键片段着色让报错在控制台中更醒目易读。关闭 FESFES 的运行时校验会带来额外开销在某些场景下你可能希望禁用 FES 以提升性能。当p5.disableFriendlyErrors设置为true时即可关闭 FESp5.disableFriendlyErrors true; function setup() { createCanvas(100, 50); }需要了解的实现细节所有检查入口都会响应这个开关_friendlyError()、fesErrorMonitor()、checkForUserDefinedFunctions()、validate()等函数的第一行都包含if (p5.disableFriendlyErrors) return;参见 fes_core.js 与 param_validator.js因此设一次即可全局生效包括关闭参数校验器p5.disableParameterValidator之外的整套 FES。压缩版自动省略 FESp5 的单个压缩文件p5.min.js通过IS_MINIFIED构建标志把 FES 相关函数替换为空操作见上文 fes_core.js因此生产环境引入压缩版本身就不会携带友好错误的代码与开销。结语FES 是 p5.js 国际化与开发者体验的重要交集它用 i18next 插值把错误消息拆解为可翻译的文本块用errorTable抹平不同浏览器的报错措辞差异用参数校验器把 API 文档元数据转化为即时反馈再以p5.disableFriendlyErrors与压缩构建提供性能开关。无论你是想为 p5.js 贡献新语言的错误翻译、改进某条报错的措辞还是在自己的项目中借鉴这套友好错误设计都可以从 translations 的 JSON 文件与 src/friendly_errors 的源码入手并结合 FES 参考 开发笔记 与 FES 贡献指南 深入实践。【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表