语言设定

p5.js 回馈指南

教程作者为 Tega Brain。

我们欢迎教育家、合作者和一般爱好者开发更多 p5.js 教程。p5.js 旨在让创意编程及开源软件开发更易接近及吸引更多元化的社群,同时我们也很高兴能够公开的发布 p5.js 开发的完整过程及教程。我们现有的教程含括了各种课题如:学习使用 p5.js、编程技巧及如何帮助开发开源项目。

我们欢迎任何人提交全新教程,这份指南将包括新教程的提议、准备和提交的所需步骤。

如何开始:

  • 先确定您所建议的课题尚未被涵盖,在此链接有一个列表 列出了正在进行中的教程。如果您想开发的课题被列为正在进行中 (in progress),您或许能帮助完成该项目或为现有的项目做预备发布的工作,您只需联络我们。
  • 如果您的课题尚未被涵盖及尚未被列为正在进行中,请寄份电子邮件去 [email protected] 并简略的讲述您所建议的教程。

如何准备网上 p5.js 教程:

当您以准备发布您的教程,请按着以下步骤准备您的教程给 p5.js 的网页。

将您的教程写在一个命名为 tutorial-name.hbs 的文件并跟从这基本结构 。如该文件所示,它必须有以下开端:

Screenshot of example header for the file referenced in previous paragraph.

您的教程文件夹将被置放在 p5.js 网站一个命名为“tutorials”的文件夹内。index.hbs 是p5.js 教程的主页 而 test-tutorial.hbs 为空白范例教程。

所有内容必须被包含在以下标签内: <section > </section> 内容格式可以使用 <h1>、<h2> 及 <p> 段落标签定义,如空白范例教程所示。

如果您的教程包含图像,它们必须被置放在 p5 网站的 asset 文件夹,该文件夹位于 src/assets/learn/test-tutorial/images 如以下所示。

Screenshot of a GitHub page showing the file path referenced in previous paragraph.

以在 HTML 页面内格式化您的源代码,请使用以下标签:


<pre><code class="language-javascript">
Your code here!
</code></pre>

嵌入 p5.js 绘图

使用 p5.js 的一个好处是您可以制作动画驱动、互动性或可编辑的教程,方便更简易的演示程式设计概念。您的范例必须是 p5.js 绘图而它能用以下两种方式嵌入在您的教程中。

  1. 如果该范例需保持可编辑性,如在 p5.js 网站的参考文献内,该 p5 绘图必须使用 p5.js 部件以嵌入在 HTML 页面内,请使用这指南以了解如何使用该部件嵌入 p5.js 绘图,部件Toolness。您也可以在空白范例教程内查看使用范例。
  2. 如果该范例必须是动画驱动或互动性的但并不需要是可编辑的,该 p5.js 绘图需使用 iframe 以嵌入在页面内,如以下所示。

使用 iframe 嵌入 p5 绘图

iframe 让您能在原有的页面上开启一个通往另一个页面的窗口,同时该页面并不能直接和原有页面互动。在此例, 原有页面内会被嵌入一个含有您 p5.js 绘图的 index.html 窗口。

Illustration of a p5.js iframe embedded within a HTML page.

在 /src/assets/learn 文件夹内,将您的 p5 绘图置放在一个命名为您的绘图名的文件夹内如以下截图所示。这文件夹是您置放所有 iframe 内将使用的图像及 p5 绘图的地方。

Screenshot of a GitHub page showing an example file path for tutorial photos.

在含有您的 p5 范例的子文件夹内应该含有一个 sketch.js 文件及一个 embed.html 文件。

Screenshot of a GitHub page showing an example of an embed.html file for a tutorial sketch.

请确保 embed.html 内的 p5 程式库有正确的链接。如果您的文件结构和以上相同,p5.js 程式库的链接将会是 "../../../js/p5.min.js"。

这时你可以将 p5.js 绘图文件以 iframe 的方式嵌入在您的教程的 .hbs 文件中。iframe 嵌入代码如下:


<iframe src="http://p5js.org/assets/learn/tes-tutorial/embed.html" width="600" height="400">
</iframe>

以格式化 iframe,您可以将以下包括在文件内或使用样式表:


<style> iframe{ border: none; } </style>

在以下链接您可以直接查看绘图:

http://staging.p5js.org/assets/learn/test-tutorial/embed.html

而在以下您可以查看绘图被嵌入在 p5 网页中:

http://staging.p5js.org/learn/test-tutorial.html

还有一项您需要注意的是您必须设置 iframe 的大小,以确保其大小不会随着窗口大小而改变。

另外,p5.js 程式库的文件链接并不是在 .eps 文件内(如其他教程),而是在您的 HTML 页面内(通常是 embed.html)。

更多关于嵌入 p5.js 绘图的信息可在以下链接查找。

结束

一旦您完成编辑您的教程并且您的教程已经被许可,分叉 p5.js 网站的代码库,如以上所示的步骤准备您的教程然后开启一个 pull request 给 p5.js 网站的代码库以便我们能发布您的教程!

谢谢!