java 在 javadocs 中包含图像

Including images in javadocs

提问by ianpojman

I work with a lot of sample test cases that are visual. Is there any convenient way to include them in my Java source and link them in Javadocs, so my IDE can automatically show them while coding (by invoking a javadoc renderer feature in my IDE?)

我使用了许多可视化的示例测试用例。有没有什么方便的方法可以将它们包含在我的 Java 源代码中并将它们链接到 Javadocs 中，这样我的 IDE 就可以在编码时自动显示它们（通过在我的 IDE 中调用 javadoc 渲染器功能？）

I tried putting an image next to the Java source and using <img>, but it's not taking (I used a png).

我尝试在 Java 源代码旁边放置一个图像并使用<img>，但它没有（我使用了 png）。

(note - it's in my test sources in this case)

（注意 - 在这种情况下，它在我的测试源中）

采纳答案by Pa?lo Ebermann

As you didn't show any sources, I can only do a glass-ball guess ...

由于你没有显示任何消息来源，我只能做一个玻璃球猜测......

For any files which are needed for documentation purposes, one should put them in a subdirectory named doc-filesof your package directories. These will then be simply copied by Javadoc to the output directory. Then use a relative path in the <img>element.

对于任何用于文档目的的文件，应将它们放在以doc-files包目录命名的子目录中。然后这些将被 Javadoc 简单地复制到输出目录。然后在<img>元素中使用相对路径。

I'm not sure if your IDE's Javadoc renderer will do the same, but it is worth a try.

我不确定您的 IDE 的 Javadoc 渲染器是否会做同样的事情，但值得一试。

回答by Emmanuel Bourg

A bit far fetched, but you can inline the images in the documentation by converting them into Base64. It would look like this:

有点牵强，但您可以通过将它们转换为 Base64 来内联文档中的图像。它看起来像这样：

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..." />

There are online tools available to do the conversion:

有可用的在线工具进行转换：

• http://www.base64-image.de
• http://daturi.me
• http://www.freeformatter.com/base64-encoder.html

• http://www.base64-image.de
• http://daturi.me
• http://www.freeformatter.com/base64-encoder.html

回答by Vsevolod Golovanov

With Eclipse Luna the following works for me.

使用 Eclipse Luna，以下内容对我有用。

• com
  • company
    • somepackage
      • doc-files
        • image.png
      • Test.java

• 电脑
  • 公司
    • 一些包裹
      • 文档文件
        • 图片.png
      • 测试.java

Now in Test.java's javadoc:

现在在 Test.java 的 javadoc 中：

/**
 * <img src="./doc-files/image.png" />
 */

And Eclipse shows the image both in popup help, when you hover the mouse, and in the Javadoc View.

Eclipse 会在弹出帮助、鼠标悬停时和 Javadoc 视图中显示图像。

You can even add style="width: 100%;"to the imgtag, so the image adjusts to the view/popup size.

您甚至可以添加style="width: 100%;"到img标签，以便图像调整到视图/弹出窗口的大小。

回答by Jason

To expand a little on Pa?lo's answer assuming a maven build here is what worked for me with JDK-8 (stricter HTML validation), with the stipulation that you're willing to run the javadoc tool.

为了扩展 Pa?lo 的回答，假设这里的 Maven 构建对我来说适用于 JDK-8（更严格的 HTML 验证），并规定您愿意运行 javadoc 工具。

Unfortunately with Netbeans I cannot see the image in the IDE's javadoc popup, I just opened this netbeans bug.

不幸的是，使用 Netbeans 我无法在 IDE 的 javadoc 弹出窗口中看到图像，我刚刚打开了这个 netbeans bug。

Assume this is part of the javadoc for com.foo.File.java (notice no img end tag, which is the right way per w3schools):

假设这是 com.foo.File.java 的 javadoc 的一部分（注意没有 img 结束标记，这是每个 w3schools 的正确方法）：

<img src="doc-files/foo.png" alt="Foo">

In the maven directory structure you'll find the image here: src/main/javadoc/com/foo/doc-files/foo.png

在 maven 目录结构中，您将在此处找到图像： src/main/javadoc/com/foo/doc-files/foo.png

And last, in the pom.xml (notice docfilessubdirsis set to true):

最后，在 pom.xml 中（注意docfilessubdirs设置为 true）：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.3</version>
            <configuration>
                <docfilessubdirs>true</docfilessubdirs>
            </configuration>
        </plugin>
        ...

回答by Сергей Камынин

Try this way

试试这个方法

/**
 * @author KamyninSA
 * @version 1
 * <p><b>Description</b></p>
 * <p><img src="{@docRoot}/../src/test/resources/doc-files/ads.png" alt="alternative directory"></p>
 * */

回答by BAERUS

I stumbled upon this question as I as well wanted to show a preview of my icons. After reading the answers, I was not yet satisfied and tried it for myself. That's what I now got:

我偶然发现了这个问题，因为我也想显示我的图标的预览。看了答案，还不满意，自己试了一下。这就是我现在得到的：

     /**
     * <img src="../../../../../../resources/com/my/project/client/images/myImage.png"><br>
     * Icon for myImage.
     *
     * @return the icon
     */

like this I don't need to manage more images than before by simply going to the folder the actual images lie in.

像这样，只需转到实际图像所在的文件夹，我就不需要管理比以前更多的图像。

回答by Roger Neyman

To expand a bit on Vsevolod Golovanov and Paulo Ebermann's answer above, here is a concrete example and further elaboration.

为了稍微扩展 Vsevolod Golovanov 和 Paulo Ebermann 的回答，这里有一个具体的例子和进一步的阐述。

The Javadocs documentation states:

Javadocs 文档指出：

To include unprocessed files, put them in a directory called doc-files which can be a subdirectory of any package directory that contains source files.

要包含未处理的文件，请将它们放在名为 doc-files 的目录中，该目录可以是包含源文件的任何包目录的子目录。

If you place the image files in that folder they will be available to the Javadocs HTML files via the relative path from the generated HTML.

如果您将图像文件放在该文件夹中，它们将可通过生成的 HTML 的相对路径供 Javadocs HTML 文件使用。

So, if your project is named MyProjectand the class you are adding Javadoc commentary to is org.foo.app.MyApp, the source folder for which is MyProject/src/org/foo/app/MyApp.javaand you want to include MyImage.jpgin it's Javadoc, then:

因此，如果您的项目名为MyProject并且您要向其添加 Javadoc 注释的类是org.foo.app.MyApp，则其源文件夹为MyProject/src/org/foo/app/MyApp.java并且您想要包含MyImage.jpg在它的 Javadoc 中，然后：

Create the folder MyProject/src/org/foo/app/doc-files, and place the image file in it.

创建文件夹MyProject/src/org/foo/app/doc-files，并将图像文件放入其中。

At that point your Javadocs text can reference it thus:

此时，您的 Javadocs 文本可以引用它：

<img src="doc-files/MyImage.jpg" width="500" alt="description of MyImage">

And the Javadocs-generated HTML will reflect be coded accordingly.

并且 Javadocs 生成的 HTML 将被相应地编码。

Note the "width" attribute, allowing scaling of the image. The height is scaled proportionally.

注意“width”属性，允许缩放图像。高度按比例缩放。

When you run Javadocs, the doc-filesfolders will all be copied to the Javadocs output folders and the resources within them will be available for use by the HTML.

当您运行 Javadocs 时，doc-files 文件夹将全部复制到 Javadocs 输出文件夹中，并且其中的资源可供 HTML 使用。