TechDocs 附加组件

概念

TechDocs 是一个集中式平台，用于在整个组织内发布、查看和发现技术文档。这是一个坚实的基础！但它本身并不能解决更高层次的文档需求：如何创建和加强文档文化？如何建立对技术文档质量的信任？

TechDocs 附加组件是一种机制，您可以通过它来定制 TechDocs 体验，以尝试满足其中一些高阶需求。

附加组件

Addon 只是一个 react 组件。与其他 react 组件一样，它可以使用正常的Backstage或本地钩子、API 和组件来检索和呈现数据。在适当的情况下，可以使用道具来配置其行为。

###地点

附加组件声明一个location大多数位置都代表 TechDocs UI 中的物理空间：

Header: For Addons which fill up the header from the right, on the same line as the title. * Subheader: For Addons that sit below the header but above all content. This is a great location for tooling/configuration of TechDocs display. * Settings: These addons are items added to the settings menu list and are designed to make the reader experience customizable, for example accessibility options. * PrimarySidebar: Left of the content, above of the navigation. * SecondarySidebar: Right of the content, above the table of contents. * Content: A special location intended for Addons which augment the statically generated content of the documentation itself. * Component: A proposed-but-not-yet-implemented virtual location, aimed at simplifying a common type of Addon.

TechDocs Addon Location Guide

Addon Registry

插件的安装和配置在Backstage程序的前台进行，插件从插件中导入，并添加到一个名为<TechDocsAddons>该注册表既可以为 TechDocs 阅读器页面配置，也可以为实体文档页面配置。

附加组件按注册顺序呈现。

安装和使用附加组件

要开始使用附加组件，您需要添加@backstage/plugin-techdocs-module-addons-contrib从项目根目录运行此命令即可：yarn add --cwd packages/app @backstage/plugin-techdocs-module-addons-contrib

附加组件的安装和配置方式与其他 Backstage 插件的扩展基本相同：通过将它们添加到扩展注册表组件 (<TechDocsAddons>中代表 TechDocs 阅读器页面的路由下的App.tsx:

// packages/app/src/App.tsx

import { TechDocsReaderPage } from '@backstage/plugin-techdocs';
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';

// ...

<Route path="/docs/:namespace/:kind/:name/*" element={<TechDocsReaderPage />}>
  <TechDocsAddons>
    <ReportIssue />
    {/* Other addons can be added here. */}
  </TechDocsAddons>
</Route>;

如果使用自定义TechDocs 读者页面您的设置将非常相似，下面是一个例子：

<Route path="/docs/:namespace/:kind/:name/*" element={<TechDocsReaderPage />}>
  <TechDocsAddons>
    <ReportIssue />
    {/* Other addons can be added here. */}
  </TechDocsAddons>
  {techDocsPage} // This is your custom TechDocs reader page
</Route>

在实体页面的文档选项卡上配置附加组件的过程非常相似，但不是添加<TechDocsAddons>登记册下的<Route>的子代，您可以将其添加为<EntityTechdocsContent />:

// packages/app/src/components/catalog/EntityPage.tsx

import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityTechdocsContent } from '@backstage/plugin-techdocs';
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';

// ...

<EntityLayout.Route path="/docs" title="Docs">
  <EntityTechdocsContent>
    <TechDocsAddons>
      <ReportIssue />
      {/* Other addons can be added here. */}
    </TechDocsAddons>
  </EntityTechdocsContent>
</EntityLayout.Route>;

请注意，在实体页面上，由于目录插件负责页面页眉，因此位置为Header将不会显示。

可用插件

原则上，任何插件都可以提供附加组件！为了方便用户发现可用的附加组件，我们在此编制了一份清单：

| Addon | Package/Plugin | Description | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |[<ExpandableNavigation />``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation)|@backstage/plugin-techdocs-module-addons-contrib| 允许 TechDocs 用户展开或折叠整个 TechDocs 主导航，并在文档站点之间保持用户的首选状态。[报告问题 />``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue)|@backstage/plugin-techdocs-module-addons-contrib| 允许 TechDocs 用户选择 TechDocs 页面上的部分文本，并针对包含文档的资源库打开一个问题，根据可配置的模板将所选文本填充到问题描述中。[<TextSize />``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize)|@backstage/plugin-techdocs-module-addons-contrib| 这个 TechDocs 附加组件允许用户自定义文档页面上的文字大小，用户可以通过滑块或按钮选择增大或减小字体的大小。字体大小的默认值为 100%，无论何时更改，该设置都会保存在浏览器的本地存储中。[<灯箱 />``](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox)|@backstage/plugin-techdocs-module-addons-contrib| 该 TechDocs 附加组件允许用户在文档页面的灯箱中打开图片，如果一个页面上有多个图片，用户可以在图片之间进行导航。灯箱图片的大小与文档页面上的图片大小相同。点击缩放图标后，图片会缩放以适应屏幕大小(类似于"......")。background-size: contain`). |

您有要贡献的插件吗？请在上面添加一行！

创建插件

最简单的附加组件就是在 TechDocs 网站的特定位置呈现的普通老式 React 组件。要将此类 React 组件打包为附加组件，请按照以下步骤操作：

1.像编写其他组件一样在插件中编写组件 2.创建、提供并从插件中导出组件

// plugins/your-plugin/src/plugin.ts

import {
  createTechDocsAddonExtension,
  TechDocsAddonLocations,
} from '@backstage/plugin-techdocs-react';
import { CatGifComponent, CatGifComponentProps } from './addons';

// ...

// You must "provide" your Addon, just like any extension, via your plugin.
export const CatGif = yourPlugin.provide(
  // This function "creates" the Addon given a component and location. If your
  // component can be configured via props, pass the prop type here too.
  createTechDocsAddonExtension<CatGifComponentProps>({
    name: 'CatGif',
    location: TechDocsAddonLocations.Header,
    component: CatGifComponent,
  }),
);

内容位置中的附加组件

除了 "在区域中渲染组件 "的用例之外，Addons 还可以访问和操作 TechDocs 网站的 DOM；例如，这可用于加载和实例化客户端图表库，用动态加载的内容替换元素等。

这种类型的 Addon 仍以 react 组件的形式表示，但它不是返回一个要渲染的 react 元素，而是通过副作用更新 DOM(例如用useEffect通过 Addon 框架提供的实用钩子可以访问 DOM。

// plugins/your-plugin/src/addons/MakeAllImagesCatGifs.tsx

import React, { useEffect } from 'react';
import { useShadowRootElements } from '@backstage/plugin-techdocs-react';

// This is a normal react component; in order to make it an Addon, you would
// still create and provide it via your plugin as described above. The only
// difference is that you'd set `location` to `TechDocsAddonLocations.Content`.
export const MakeAllImagesCatGifsAddon = () => {
  // This hook can be used to get references to specific elements. If you need
  // access to the whole shadow DOM, use the the underlying useShadowRoot()
  // hook instead.
  const images = useShadowRootElements<HTMLImageElement>(['img']);

  useEffect(() => {
    images.forEach(img => {
      if (img.src !== 'https://example.com/cat.gif') {
        img.src = 'https://example.com/cat.gif';
      }
    });
  }, [images]);

  // Nothing to render directly, so we can just return null.
  return null;
};

测试插件

安装@backstage/plugin-techdocs-addons-test-utils作为devDependency在您的插件中，以访问实用程序，从而更轻松地测试此类插件。

对上述插件的测试可能是这样的

// plugins/your-plugin/src/addons/MakeAllImagesCatGifs.test.tsx
import { TechDocsAddonTester } from '@backstage/plugin-techdocs-addons-test-utils';

// Note: import your actual addon (the one provided by your plugin).
import { MakeAllImagesCatGifs } from '../plugin.ts';

describe('MakeAllImagesCatGifs', () => {
  it('replaces img srcs with cat gif', async () => {
    const { getByTestId } = await TechDocsAddonTester.buildAddonsInTechDocs([
      <MakeAllImagesCatGifs />,
    ])
      .withDom(<img data-testid="fixture" src="http://example.com/dog.jpg" />)
      .renderWithEffects();

    expect(getByTestId('fixture')).toHaveAttribute(
      'src',
      'https://example.com/cat.gif',
    );
  });
});

概念​

附加组件​

Addon Registry​

安装和使用附加组件​

可用插件​

创建插件​

内容位置中的附加组件​

测试插件​

概念