使用 JavaScript 改进您的文档

图片来源

原始照片由 Marco Tedaldi 拍摄。由 Rikki Endsley 修改。CC BY-SA 2.0 许可。

开源软件项目通常拥有非常多样化的用户群体。一些用户可能非常擅长使用系统，只需要很少的文档。对于这些高级用户，文档可能只需要作为提醒和提示，并且可以包含更多技术信息，例如在 shell 中运行的命令。但是其他用户可能是初学者。这些用户在设置系统和学习如何使用系统方面需要更多帮助。

编写适合两个用户群体的文档可能令人生畏。网站的文档需要以某种方式平衡“详细的技术信息”和“提供更多概述和指导”。这是一个难以找到的平衡点。如果您的文档无法满足两个用户群体，请考虑第三种选择——动态文档。

了解如何向网页添加少量 JavaScript，以便用户可以选择仅显示他们想要查看的信息。

构建您的内容

您可以使用文档需要同时适合专家用户和新手用户的示例。在最简单的情况下，您可以使用一个虚构的音乐播放器，名为 AwesomeProject。

您可以使用 HTML 编写一个简短的安装文档，通过使用 HTML 中的 class 功能，为专家和新手提供说明。例如，您可以使用以下代码定义一个面向专家的段落

<p class="expert reader">

这同时分配了 expert 类和 reader 类。您可以创建一组针对新手的并行指令，使用

<p class="novice reader">

完整的 HTML 文件包含针对新手读者和专家的段落

<!DOCTYPE html>

<html lang="en">

<head>

<title>How to install the software</title>
</head>

<body>

<h1>How to install the software</h1>

<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>

<p>But first, we need to install it:</p>

<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run:
<code>./configure ; make ; make install</code></p>

<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package manager and search for AwesomeProject to install it.</p>

</body>

</html>

此示例 HTML 文档未关联样式表，因此在 Web 浏览器中查看时会显示这两个段落

图片来源

(Jim Hall，CC BY-SA 4.0)

我们可以对文档应用一些基本样式，以突出显示具有 reader、expert 或 novice 类的任何元素。为了使不同的文本类更容易区分，我们将 reader 类设置为灰白色背景颜色，expert 类设置为深红色文本颜色，novice 类设置为深蓝色文本颜色

<!DOCTYPE html>

<html lang="en">

<head>

<title>How to install the software</title>

<style>

.reader {
background-color: ghostwhite;
}

.expert {
color: darkred;
}

.novice {
color: darkblue;
}

</style>

</head>

<body>

<h1>How to install the software</h1>

当您在 Web 浏览器中查看页面时，这些样式有助于突出显示这两个部分。由于安装说明的两个段落都具有 reader 类，因此都具有灰白色背景颜色。第一个段落使用深红色文本，由 expert 类定义。第二个安装段落是深蓝色文本，来自 novice 类

图片来源

(Jim Hall，CC BY-SA 4.0)

我们最喜欢的关于开源的资源

添加 JavaScript 控件

应用这些类后，您可以添加一个简短的 JavaScript 函数，该函数仅显示其中一个内容块。编写此函数的一种方法是首先将 display:none 设置为所有具有 reader 类的元素。这将隐藏内容，使其不会显示在页面上。然后，该函数应将 display:block 设置为您要显示的类的每个元素

<script>
function readerview(audience) {
  var list, item;
  // hide all class="reader"
  list = document.getElementsByClassName("reader");
  for (item = 0; item < list.length; item++) {
    list[item].style.display = "none";
  }
  // show all class=audience
  list = document.getElementsByClassName(audience);
  for (item = 0; item < list.length; item++) {
    list[item].style.display = "block";
  }
}
</script>

要在 HTML 文档中使用此 JavaScript，您可以将该函数附加到按钮。由于 readerview 函数将受众作为其参数，因此您可以使用要查看的受众类（novice 或 expert）调用该函数

<!DOCTYPE html>

<html lang="en">

<head>

<title>How to install the software</title>

<style>

.reader {
background-color: ghostwhite;
}

.expert {
color: darkred;
}

.novice {
color: darkblue;
}

</style>

</head>

<body>

<script>

function readerview(audience) {
  var list, item;

  // hide all class="reader"

  list = document.getElementsByClassName("reader");

  for (item = 0; item < list.length; item++) {

    list[item].style.display = "none";
  }

  // show all class=audience

  list = document.getElementsByClassName(audience);

  for (item = 0; item < list.length; item++) {

    list[item].style.display = "block";
  }

}

</script>

<h1>How to install the software</h1>

<nav>

<button onclick="readerview('novice')">view novice text</button>

<button onclick="readerview('expert')">view expert text</button>

</nav>

<p>Thanks for installing AwesomeProject! With AwesomeProject,
you can manage your music collection like a wizard.</p>

<p>But first, we need to install it:</p>
<p class="expert reader">You can install AwesomeProject from
source. Download the tar file, extract it, then run
<code>./configure ; make ; make install</code></p>

<p class="novice reader">AwesomeProject is available in
most Linux distributions. Check your graphical package
manager and search for AwesomeProject to install it.</p>

</body>

</html>

有了这些控件，网页现在允许用户选择他们想要查看的文本