Артефакт для написания документов на основе компонентов Vite, быстрый и беззаботный

СейчасViteЭкология постепенно улучшается.Сегодня я представлюReactАртефакт написания документации компонента/приложения:vite-plugin-react-pages

Текущий основной способ создания сайта документации:

1. GATSBY - GraphQL как основной функцию довольно хорошо, богатая булочками экологии. Но кривая обучения высока (реагировать)
2. Докузавр — представлен Метой. Мощный, похожий на Гэтсби (React)
3. dumi — инструмент документирования разработки компонентов (React) в экосистеме UmiJS.
4. Nextra — генератор статических сайтов на основе Next.js. (Реагировать)
5. VuePress — содержит систему тем и плагин API на базе Vue, другая часть — это тема по умолчанию (Vue), оптимизированная для написания технической документации.
6. VitePress — множество улучшений VuePress. VitePress стремится упростить текущий VuePress и начать все заново с его минималистских корней. (Вью)

КромеVitePressСнаружи, другие используютсяWebpackкак сервер разработки. Время, необходимое для запуска сервера разработки для простого сайта документации всего с несколькими страницами, становится невыносимым. даже еслиHMRОбновления также могут занять несколько секунд, чтобы отобразиться в браузере.ViteПоявление , прекрасно решает эти проблемы: почти мгновенный запуск сервера, компиляция по требованию, которая компилирует только те страницы, которые она обслуживает, и молниеноснаяHMR.

так какViteна основании схемы документации,VitePressтолько поддержкаVue.

пролистыватьViteОфициальный список библиотек и наткнулся на решение для документации с более чем 100 звездами.vite-plugin-react-pages. Я начал испытывать это с менталитетом тестирования воды, и это оказалось весьма полезным. Просто мало кто знает. Теперь давайте проанализируем его полезные функции с точки зрения пользователя.

характеристика

vite-plugin-react-pages(vite-страницы) — этоviteПредоставить поддержкуReactкаркас приложения. Он идеально подходит для:

• сайт блога
• Сайт документации для библиотеки компонентов или продукта
• ReactкомпонентDemoдемо

Он предоставляет много помощи разработчикам для быстрого созданияReact Appфункция:

• большой опыт разработки.即使有很多页面，也可以极速启动本地开发服务器。 HMR 适用于Reactа такжеMDX, так что вы можете получать мгновенные отзывы об обновлениях при редактировании кода.
• маршрутизация на основе файловой системы. Страницы можно легко создавать, размещать и разрабатывать, следуя простым соглашениям о маршрутизации файловой системы. также можно настроитьvite-pagesКак найти файлы подкачки для поддержки проектов любой файловой структуры.
• служба поддержкиMDX.可以使用 “普通 React” 或MDXПишите контент. «Обычный ответ» противMarkdownГибкая композиция, более читаемая и легко редактируемая.
• Мощная настройка темы.vite-pagesсам по себе не дает никаких конкретныхDOMузел. Используя официальную библиотеку тем по умолчанию, также легко создать тему самостоятельно, которая может настроить практически все на странице.
• Автоматическое кодовое расщепление на основе страниц. Загружайте данные текущей страницы только по мере необходимости при посещении.
• Компонент поддержки и предварительный просмотр кода. Увидев функцию компонента, вы можете увидеть, как компонент используется в коде.
• служба поддержкиtypescriptИзвлечение типа. БудуtypescriptВведите определения и комментарий Born становится формой документа API компонента.
• служба поддержкиSSRиз коробки. За счет предварительного рендеринга приложения в HTML во время сборки пользователи могут видеть содержимое до того, как загрузится какой-либо JS.

использовать

vite-pagesПо умолчанию предоставляются три шаблона, вы можете инициализироватьapp (приложение), lib (библиотека компонентов), lib-monorepo

Вы можете создать свой собственный начальный репозиторий с помощью команды

npm init vite-pages [仓库名] --template [模板名]

мы выступаемnpm init vite-pages library-demo --template libгенерирует типичныйViteСтруктурированные проекты со знакомымиvite.config.ts,pagesпапки и т. Д.

Все явные зависимости функции плагина:

• @mdx-js/mdx MDXреализация
• @mdx-js/реагировать какMDXизReactвыполнить.
• MDXплагин
• vite-pages-theme-doc 官方的文档主题。 полагатьсяreact-router-dom^ Версия 5.0.0

Каталог страниц является записью документа. Соглашение о маршрутизации на основе файлов идентифицируется как страница документации по окончанию имени файла знаком $.

.ts|.tsx|.js|.jsx|.md|.mdx Все расширения файлов допустимы, если последним символом перед расширением является $.

Путь к файлу	URL-адрес страницы
index$.tsx	/
$.tsx (с индексом$.tsx имеет тот же эффект)	/
page-one$.tsx	/page-one
page-two$.md	/page-two
dir-name/page-three$.mdx	/dir-name/page-three
dir-name/[id]/index$.tsx	/dir-name/:id

В каталоге страниц также есть специальная запись_theme.tsxИспользуется для настройки темы текущего документа,vite-pagesиспользуется по умолчаниюvite-pages-theme-docОфициальная тема. Если требования к настройке невелики, вы можете реализовать обычные функции, настроив параметры официальной темы. Например, настроить логотип, верхнюю ссылку, левое меню и т. д.

Давайте посмотрим на код документа главной страницы.

---
title: 首页
---

import README from '../README.md'

<README />

README.mdMDXЗдесь документация и компоненты хорошо сочетаются друг с другом.

Затем создайте новый документ и вставьте тему, которая была написана ранее.

Меню будет отдавать приоритет использованию имениmd文件中的一级标题，否则使用文件名。 также доступен вmdДобавьте следующие настройки кода в первую строку файла:

---
title: mac-scrollbar
group: components
subGroup: general
---

groupГруппировка первого уровня будет отображаться в области списка заголовков;subGroupГруппировка второго уровня будет отображать левое меню в группах.

в состоянии пройти_theme.tsxИзменить название группы и групповой порядок

sideNavs: (ctx) => {
  return defaultSideNavs(ctx, {
    groupConfig: {
      components: {
        general: {
          label: '通用',
          order: 1,
        },
        dataRecord: {
          label: '数据录入',
          order: 2,
        },
      },
    },
  });
};

Опыт написания документов с ним неплох,markdownТема идет по умолчаниюgithubСтиль, типографика четкие. Горячее обновление — это здорово, и вы можете увидеть эффект сразу после внесения изменений.

Далее, давайте используем его для создания компонента, чтобы увидеть, как он работает, и создадим самый простой компонент кнопки.

Во-первых, определение типа компонента:

export interface ButtonProps extends React.HTMLAttributes<HTMLButtonElement> {
  /**
   * 类型
   * @defaultValue 'default'
   */
  type?: 'primary' | 'default' | 'text';
  /**
   * 尺寸
   * @defaultValue 'middle'
   */
  size?: 'large' | 'middle' | 'small';
  /**
   * 加载状态
   * @defaultValue false
   */
  loading?: boolean;
}

Простая реализация:

import React from 'react';
import { ButtonProps } from './types';
import styles from './style.module.css';

const Button = ({ className, type, ...props }: ButtonProps) => {
  return (
    <button
      {...props}
      className={[styles.button, type === 'primary' && styles.primary, className].filter(Boolean).join(' ')}
    />
  );
};

export default Button;

/**
 * @title 基本按钮
 * @description 一个很普通的按钮
 */

import React from 'react';
import { Button } from 'my-lib';

const Demo1 = () => {
  return <Button>按钮</Button>;
};

export default Demo1;

Наконец, введение этих документов в демо-версию

---
title: Button
subGroup: general
---

# Button

一个简单的按钮组件

<Demo src="./demos/demo1.tsx" />

<Demo src="./demos/demo2.tsx" />

Использование его для отладки компонентов совершенно не беспокоит.Завершение отладки означает, что документация также написана, и есть автоматически извлеченные демонстрации кода.из коробки.

Очень важной частью компонента является документация API, если ее можно автоматически загрузить сtypescriptПросто извлеките комментарии. Вот так,vite-pagesЭта функция поддерживается.

просто нужноMDXвведен вTsInfoкомпонента и задайте адрес и имя типа:

<TsInfo src="./types.ts" name="ButtonProps" />

БудуtsТип извлекает таблицу, которая распознает обязательные/описание/значения по умолчанию и т. д. С этой функцией вам не нужно беспокоиться о проблеме разделения документа и кода.

В настоящее время официальная тема этого плагина тяготеет к режиму компонентного документа с полным набором основных функций и без каких-либо дополнительных функций. Если вы хотите добиться предварительного просмотра компонентов в режиме онлайн, вы можете разветвитьvite-pages-theme-docЭта библиотека может затем изменить в стиль, который вы хотите, добавитьreact-liveПоддержка предварительного просмотра онлайн-редактирования в реальном времени.

Официальный вариант по умолчанию не предоставляет тему блога. Это не сложно сделать самому, потому чтоvite-plugin-react-pagesне оказывает никакогоDOMNode, все, что связано с рендерингом, можно загрузить сvite-pages-theme-docИзменено в этой библиотеке.

намекать

Обобщите текущую точку зрения использования, использование плагина будетViteАвтоматическая инвалидация зависимостей перед сборкой. вам нужно вручнуюnode_modulesoptimizeDeps.includeсередина. Напримерvite-pages-theme-doc,lodashПодождите, иначе будут повторные обновления при открытии страницы.

github: GitHub.com/Вите есть/Вите…

МогуДобавить Реагирующую группу一起交流学习进步。 Нет публики:前端星辰

• Это может стать нормой веб-грамматики, обсессивно-компульсивное расстройство больше не выдержит
• Как написать более элегантные компоненты React — дизайн-мышление
• Как написать более элегантные компоненты React — структура кода
• Итоги на конец 2021 года, куда должен пойти 8-летний интерфейс?
• Интервью идет на дно вопроса: каково результат выполнения [... undefined]?
• Бутик-компонент React: mac-scrollbar
• Мы перешли с UmiJS на Vite
• Как писать более элегантный код — статьи по JavaScript