Snap.js

一个复制粘贴库。

查看构建好的网站 在这里。

贡献

我是一个很有主见的人，对于网站中包含的内容、措辞等方面会非常挑剔。

如果你想提交一个 PR 来修正我一些糟糕的拼写/语法，或者在其他小方面帮助改进，那太好了！这将非常令人感激。

如果你想看到更大的变更或添加，我建议先在 GitHub issues 中讨论你期望的变更。如果你突然提交一个 PR，那也没关系，但请不要惊讶于我可能会用我自己的想法对其进行彻底修改或完全拒绝。

项目结构

网站内容以 markdown 文件的形式存储在 content/ 目录中。在部署之前，会运行一个脚本，将 content/ 中的所有文件合并为几个 json 文件。这些 json 文件将被网页用于填充自身。它们也会被测试运行器用于运行其中包含的自动化测试。

其余的源代码位于 app/ 目录中。

一个典型的文档条目文件夹将包含以下部分或全部内容：

• manifest.json - 包含此文档条目的元数据。
• description.md - 此条目的实际描述。
• src.js - （可选）一个实用函数的完整实现。这些文件仅用于网站的“Simple Utilities”部分。对于“Lodash Replacements”，请始终将代码放入 description.md 文件中（这会使条目之间看起来更加一致）。
• test.js - （可选）此文档条目中代码的测试文件。你需要将函数复制粘贴到测试文件中以进行测试。
• notes.txt - （可选）你可能希望为维护者提供的任何额外备注，且你不想将其包含在网页本身中。

在更新 description.md 文件时，如果你注意到该文件夹还包含一个 test.js 文件，请检查其内容。test.js 文件中可能包含一个来自 description.md 的函数副本，并且它正在尝试测试该函数。

Commands

使用 npm ci 安装依赖项。

要启动开发服务器，请使用 npm start。如果你正在修改 content/，你还需要运行 npm run build:watch，这将为你自动构建 content/ 文件夹。

在提交之前，请记得先运行 npm test 和 npm run lint:fix。第一个命令将运行一系列测试，第二个命令将对项目的大部分进行 lint 检查。UI 本身没有经过测试，但一些实用函数配有自动化测试。

其他可用命令：

• npm run predeploy 运行 linter 和测试
• npm run deploy 自动运行 predeploy 并发布此网页。

Lodash 文档条目的精神

为了了解我在编写这些 Lodash 文档条目时所追求的风格，请查看 Lodash Replacements 页面 上的 FAQ 部分。简而言之，以下是我一直在遵循的准则（而非规则）：

• 问自己“这个 Lodash 函数试图解决什么问题”，然后问自己如果不使用 Lodash 你会如何解决这个问题。这可能会使你的解决方案与 Lodash 的解决方案行为大相径庭，这没关系——只需记录重要的差异即可。（对于不重要的差异，优先保持与 Lodash API 的一致性——即如果没有实际理由，不要为你的工具函数版本使用不同的函数签名）。在某些情况下，你的解决方案甚至可能不是一个工具函数，有时解决问题的方法是在编码时遵循某种模式，或使用语言为你提供的语法等。有时存在多个具有不同优缺点的解决方案，最好解释所有这些解决方案。
• 如果两个解决方案具有相同的大 O 复杂度，展示更可维护的那个。换句话说，不要进行微观优化。如果两个解决方案具有不同的大 O 复杂度，仍然优先展示更可维护的那个，但也许可以留下一个注释，说明其性能有改进空间，或者你甚至可以展示两个解决方案，让用户选择最适合他们的那个。
• Lodash 的实现并不总是遵循现代最佳实践。一些示例：
• 他们喜欢重载函数，使其根据传入的数据类型表现出多种不同的行为（在一定程度上，这没问题，但有时会被过度使用）。最好将这些视为在同一个函数中解决的不同问题，这意味着你需要为每个被解决的问题提供一份解决方案列表。
  • 他们习惯于将本不应可选的参数设为可选。如果你无法想到一个合理的理由让某人故意省略某个参数，那么就不要在你的非 Lodash 替代方案中支持这种“使用场景”。
  • 如果你给 Lodash 一个错误的参数，他们喜欢尝试将其强制转换为可用的东西，而不是抛出错误。不要在你的非 Lodash 替代函数中支持这一点。鼓励最终用户修改这些辅助函数以符合其项目的风格，这可能意味着“不要对错误参数进行任何显式处理，因为那会在代码库中产生太多噪音”，或者“对错误参数抛出运行时错误”，或者“添加 TypeScript 类型定义”。本网站的职责只是以最简形式提供解决方案，以便在需要时易于在其基础上构建。
  • 某些 Lodash 函数根本不应该被使用。在这种情况下，解释为什么使用给定的函数是个坏主意，然后无论如何提供一个非 Lodash 替代方案。

代码示例格式

以下是我一直在努力遵循的一般性准则。由于各种原因，这些准则经常被打破——有时是无意的，很多时候我只是觉得在特定场景下打破它们看起来更好。

• 如果你的代码块中包含一个不完整的表达式，请省略该表达式末尾的分号。例如，如果该行仅包含 array.map(x => x + 1)，则不应显示分号——该行代码本身没有意义，预期读者会在其上使用之前向该行添加更多内容。
• 如果你想展示某行代码的求值结果或输出内容，请使用 // =>，后跟其输出。
  • 如果代码块中只有一行代码，则优先将 // => 单独放在代码行之后的新行上。否则，优先将其放在所描述代码的同一行上。
  • 对于简单的示例，优先避免使用 console.log()，而是直接写出表达式，后跟一个 // => 注释。

linter 会运行于 markdown 条目中的代码示例，但为了使其更宽松，已禁用了各种规则。例如，由于上述指南通常建议在未完成的行上省略分号，因此它不会检查分号的使用。此外，在许多情况下，linter 需要针对代码块完全禁用，例如，如果单个代码块包含对象字面量——它将被解析为块并可能导致错误。在这些场景中，可以使用 <!-- eslint-skip --> 来跳过其解析。

如果您希望展示定义变量的多种方法，请在单独的代码块中显示每个示例。当向用户展示时，这些代码块会被拼接在一起，使其看起来像一个长的代码块（带有几个小差异）。如果您不这样做，linter 会因变量重新声明而抛出解析错误，并因此拒绝对该代码块中的任何内容进行 lint。

更新 Snap 框架代码

snap 框架的实际源代码包含大量 pragma，用于描述如何解析和呈现框架的各个部分。pragma 解析代码有些脆弱，但它能完成任务，但这意味着每次您对源代码进行更改时，务必密切关注其在渲染页面上的外观。它在完全文档模式和“经典”模式下看起来是否正常？它在移动视图下看起来是否正常？示例能否正常打开并运行？

当您对框架的更新完成后，有若干位置需要更新为新信息：

1. 将新版本添加到 framework/ 文件夹。可以使用 minify-js.com 等在线工具创建压缩版本。
2. 更新框架源文件顶部的文档链接。
3. 更新变更日志。
4. 统计不含空白或注释的行数。我使用 npm 上的 "cloc" 工具（npx cloc ./snapFramework.js）。
5. 在可用版本列表中注册新的框架版本及其行数。在项目内搜索 §u5gEq 以了解粘贴位置。
6. 更新项目以使用框架的最新版本。

版本号遵循以下模式。给定版本号 X.Y：

• X：破坏性变更
• Y：新增功能或修复错误

如果您仅修改 js-doc 注释，可以直接进行修改而无需提升版本号，也无需更改任何统计数据（因为没有任何统计数据衡量注释）。