ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

p5.js Friendly Error System(FES)完全指南:机制、i18n 消息编写与关闭方式

p5.js Friendly Error System(FES)完全指南:机制、i18n 消息编写与关闭方式 p5.js Friendly Error SystemFES完全指南机制、i18n 消息编写与关闭方式【免费下载链接】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 SystemFES以 为标志是一项面向初学者设计的友好报错机制它在浏览器原生 console 报错之外补充了更易懂的错误描述与参考文档链接并深度集成了基于 i18next 的多语言国际化能力。本文以 contributor_docs/friendly_error_system.md 为骨架结合 src/friendly_errors/ 与 translations/ 的源码实现完整讲解 FES 的设计理念、翻译文件结构与插值语法、消息生成与显示链路、关闭方式以及贡献友好错误消息的实操方法。FES 是什么FES 的目标是帮助编程新手更快地定位和修复问题当浏览器抛出错误、用户代码调用了 p5.js API 参数不合法、或出现其他适合给出提示的自定义场景时FES 会在浏览器 JavaScript 控制台以及 p5.js Web Editor 的控制台打印一条以 p5.js says: 为前缀的友好错误消息并在消息末尾附带指向 p5.js 参考文档或相关教程的链接替代默认晦涩的浏览器报错文本。需要特别注意的是p5.js 的压缩单文件构建 p5.min.js 会自动省略 FES只有未压缩的完整构建p5.js包含该功能构建时IS_MINIFIED标记会把_friendlyError等函数替换为空操作见 src/friendly_errors/fes_core.js。因此当你在正式环境中遇到缺失友好提示的情况先检查是否加载的是 min 版本。从架构上看FES 的核心代码位于仓库的src/friendly_errors/目录原文档中写作src/core/friendly_errors实际仓库布局略有差异翻译数据则位于translations/目录其中包含en/、es/、hi/、ja/、ko/、zh/等多语言文件夹。设计理念降低调试门槛FES 的设计遵循工具的设计应当匹配使用者的需求这一原则。为了验证现有设计是否真正降低了调试门槛p5.js 团队在 2021 年面向社区开展了一次友好错误专项调研收集用户对 Friendly Errors 的反馈与期望调研结论以漫画摘要和完整报告两种形式公开可供贡献者参考相关链接收录于原文档中。由此沉淀出的核心设计原则是错误消息的编写者应优先考虑降低读者理解错误消息的门槛、提升调试过程的可及性。具体包括了解受众不要对错误消息的受众做臆断主动了解谁在使用这个库、如何使用语言包容性努力让消息真正友好审视语言中可能存在的偏见与伤害并遵守 CODE_OF_CONDUCT.md尽量使用简单句可将长句拆分为小块以便更好地利用 i18next 的插值interpolation特性重视跨文化沟通为不同语言提供一致的优秀体验避免使用修辞手法如比喻、双关一次只引入一个技术概念或术语保持技术写作的一致性并为初学者链接一个语言友好、短小实用示例丰富的外部资源。消息的国际化i18ntranslator() 与翻译文件FES 是 p5.js 国际化internationalization工作的一部分。所有 FES 消息内容都通过基于 i18next 的translator()函数动态生成——注意包括英语在内的一切语言都是这样生成的英语只是默认语言。这意味着你不需要在代码里写死任何文案只需要维护翻译 JSON 即可。翻译文件位置translator()根据浏览器检测到的语言代码从如下路径读取文本数据translations/{{detected locale code, defaulten}}/translation.json例如当浏览器语言为韩语语言代码ko时translator()会读取 translations/ko/translation.json 中的文本块并组装出最终消息。语言代码还可以包含地区信息例如es-PE秘鲁西班牙语。翻译文件结构translation.json采用 i18next 的 JSON 格式基本单元是键-值对键与值都用双引号包裹整体由花括号闭合{ key: value }例如 FES 的 ASCII logo 就保存在这种格式中\n表示换行logo: _ \n /\\| |/\\ \n \\ / \n / , . \\ \n \\/|_|\\/ \n\n实际查看 translations/ko/translation.json 可以看到完整的消息树结构顶层是fes命名空间其下按错误类别组织例如fes.fileLoadError文件加载错误、fes.friendlyParamError参数校验错误、fes.globalErrors浏览器全局错误再细分为reference、syntax、type三类等。插值Interpolationi18next 支持插值用双花括号{{}}声明变量占位符调用时传入实际值即可动态组装消息。例如greeting: Hello, {{who}}!键为greeting变量名为who。动态生成该消息时传入值translator(greeting, { who: everyone });translator生成的结果为Hello, everyone!FES 中fileLoadError下的image条目就是插值的典型示例image: It looks like there was a problem loading your image. {{suggestion}}FES 在捕获到图片加载错误时会预先拼装好suggestion提示检查文件路径、托管文件或运行本地服务器再调用translator(fes.fileLoadError.image, { suggestion });生成类似 p5.js says: It looks like there was a problem loading your image. Try checking if the file path (...) is correct, hosting the file online, or running a local server. 的完整消息多语言版本可见 translations/ko/translation.json 中fileLoadError各条目。如何新增或修改翻译原文档指出新增与修改翻译文件的完整分步指南见 contributor_docs/archive/internationalization.md另有 contributor_docs/zh-Hans/archive/internationalization.md 中文版可按以下要点操作在 translations/ 下找到目标语言目录没有则按语言代码新建编辑对应translation.json在fes命名空间下按类别添加或修改键值对若新增了插值变量请确保代码调用translator()时传入了对应字段提交前可参考 translations/index.js 与 translations/dev.js 了解翻译文件的加载与开发辅助逻辑。理解 FES 的工作机制FES 的触发时机p5.js 会在多种情境下调用 FES浏览器抛出错误时如 SyntaxError、ReferenceError、TypeError以及未处理的 Promise 拒绝用户代码调用 p5.js API 时参数校验失败其他自定义场景如文件加载失败、浏览器自动播放策略被拦截等用户需要帮助提示的情形。FES 代码位置FES 的核心组件位于src/friendly_errors/翻译文件位于translations/。实际目录结构如下src/friendly_errors/fes_core.jsFES 主文件包含_report()、_friendlyError()、_fesErrorMonitor()及拼写检查、顶层误用检测等辅助函数src/friendly_errors/param_validator.js基于 Zod 与 docs/parameterData.json由函数内联文档生成实现_validateParameters()src/friendly_errors/browser_errors.js浏览器错误表errorTable与入口符号列表entryPointssrc/friendly_errors/stacktrace.js错误堆栈解析借自 stacktrace.js 项目src/friendly_errors/fes.js定义FES类与StyledMessage等消息输出基础设施src/friendly_errors/index.js将各模块注册为 p5 插件addon。消息生成器Message GeneratorsFES 中主要负责捕获错误并生成友好消息的函数有三个原文档所列完整参考见 contributor_docs/fes_contribution_guide.md_friendlyFileLoadError()捕获文件加载错误图片、字体、表格、JSON、字符串、XML、字节文件等。它会被 src/image/loading_displaying.js 中的loadImage()以及 src/io/files.js 中的loadFont()、loadTable()、loadJSON()、loadStrings()、loadXML()、loadBytes()调用。调用链为_friendlyFileLoadError→_report。错误类型以数字枚举区分见 contributor_docs/fes_contribution_guide.md 中errorType说明例如字体文件数据不可读与文件过大超限会给出不同的提示。_validateParameters()根据内联文档生成的参数数据检查 p5.js 函数调用传入的参数数量与类型。在源码层面它基于 Zod 构建 schema 注册表schemaRegistry并把 p5 类型构造器p5Constructors与常量constantsMap如ADD、ALT等纳入校验见 src/friendly_errors/param_validator.js。可在任意需要校验参数的 p5 函数内通过p5._validateParameters(FUNCT_NAME, ARGUMENTS)调用消息键为fes.friendlyParamError.*。_fesErrorMonitor()全局错误监视器处理浏览器捕获的全局错误。在 src/friendly_errors/fes_core.js 中它从Error、ErrorEvent或PromiseRejectionEvent提取错误对象解析堆栈过滤掉 p5 库内部错误再用errorTable中的正则模板匹配error.message识别出 SyntaxError无效 token、意外 token、变量重声明、const 缺初始化、return 位置错误等子类型、ReferenceError未定义、声明前访问、TypeError不可调用、读取 null/undefined 属性、const 重赋值等具体错误并给出对应解释与 MDN 链接。此外_friendlyAutoplayError()负责浏览器自动播放策略导致的媒体播放错误使用键fes.autoplay。消息显示器Message Displayer与输出链路_friendlyError()定义于 src/friendly_errors/fes_core.js是通用的消息打印入口可在 p5 的任何位置调用。例如p5._friendlyError(translator(fes.globalErrors.type.notfunc, translationObj));其内部流程为_friendlyError(message, func)首先检查p5.disableFriendlyErrors若开启关闭则直接返回否则调用_report(message, func)见 src/friendly_errors/fes_core.js。_report()会调用mapToReference()在消息末尾拼接参考文档链接load系列函数与无函数名时不追加然后交给FES.log输出——在 src/friendly_errors/fes.js 中FES.log最终以console.log打印默认前缀为 p5.js says: 并支持通过StyledMessage与style()辅助函数如red()、white()、bgBlack()、underline()为消息片段添加颜色等样式。除了上述函数FES 还包含两个面向初学者的特殊检测拼写检测misspellinghandleMisspelling()使用基于 Wagner–Fischer 算法的 Levenshtein 距离computeEditDistance()阈值EDIT_DIST_THRESHOLD 2见 src/friendly_errors/fes_core.js比较错误符号与所有公开 p5 属性提示用户可能写错的函数/常量及正确写法顶层代码误用检测misused top-level codehelpForMisusedAtTopLevelCode()检测用户在setup()/draw()之外使用 p5 全局符号的情况建议其移入setup()中。单元测试佐证FES 的消息输出在测试中可通过p5._fesLogger捕获为字符串进行断言见 contributor_docs/fes_contribution_guide.md 中_report()说明仓库 test/ 下的 FES 相关测试与 test/manual-test-examples/fes/ 中的手动测试示例涵盖参数过少/过多/类型错误、拼写错误、顶层误用、const 重赋值等场景可作为理解各错误分支的实证素材。关闭 FES在某些对性能敏感的场景下你可能希望关闭 FES 以获得更好的运行时表现。将p5.disableFriendlyErrors设为true即可p5.disableFriendlyErrors true; function setup() { createCanvas(100, 50); }从源码实现看p5.disableFriendlyErrors会在_friendlyError()src/friendly_errors/fes_core.js与_fesErrorMonitor()src/friendly_errors/fes_core.js等入口处直接短路返回同时FES类的#printMessage也会检查FES.disableFriendlyErrors标志src/friendly_errors/fes.js且p5.FES.disableFriendlyErrors通过Object.defineProperty与p5.disableFriendlyErrors联动src/friendly_errors/fes.js。需要再次强调p5.min.js 单文件压缩版自动省略 FES无需任何配置即不包含该功能只有完整构建中才存在上述开关。因此为了性能关闭 FES在生产环境通常意味着直接使用 min 版本构建。贡献友好错误消息从哪开始如果希望为 p5.js 贡献新的错误消息或翻译建议按以下路径展开通读 contributor_docs/friendly_error_system.md本文的原始依据与 contributor_docs/fes_contribution_guide.mdFES 贡献指南含各函数的完整参考与开发笔记阅读 contributor_docs/zh-Hans/how-to-add-friendly-error-messages.md如何添加友好错误消息的分步说明另有英文版 contributor_docs/how-to-add-friendly-error-messages.md参考 contributor_docs/archive/internationalization.md 完成翻译文件的新增与修改编写消息时遵守本文设计理念一节列出的最佳实践并在提交前于本地运行相关单元测试验证消息输出。总结FES 是 p5.js 面向初学者体验的关键组成部分它通过translator()与 i18next 驱动的 JSON 翻译文件实现全语言动态消息生成借助_friendlyFileLoadError()、_validateParameters()、_fesErrorMonitor()等生成器覆盖文件加载、参数校验与浏览器全局错误三大类场景最终由_friendlyError()/_report()配合FES.log输出带 p5.js says: 前缀与参考链接的控制台消息。理解其目录布局src/friendly_errors/translations/、插值语法与关闭开关p5.disableFriendlyErrors及 min 构建省略无论是使用、定制还是贡献 p5.js都能快速上手。【免费下载链接】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),仅供参考
返回列表