toc-helper

toc-helper — это плагин для автоматического создания оглавления статей.

v1 входа
v2 онлайн-демонстрация Demo

1. v2 функции

Использование упрощено, большое количество настроек было убрано, ненужные API удалены, требуется только импортировать один файл js.
Улучшена производительность, синхронизация прокрутки стала более плавной, автоматическая фиксация верхней части стала более точной.
Оглавление поддерживает автоматическое раскрытие и сворачивание.
Автоматическое позиционирование, начальное положение оглавления автоматически определяется.
Поддержка отображения, скрытия, адаптации к изменению ширины.
Поддерживает не только заголовки, но и требует предоставления атрибута data-level.
Поддерживает локальную прокрутку (кроме body, прокручиваются только элементы div с содержимым).
Поддерживает React, Vue, Svelte.

2. Использование

Браузер

Импортируйте JS:

<script src="lib/umd/index.js"></script>

esmodule импортирует lib/es/index.js

Используйте:

new TocHelper(el [, options])

npm

1. Установка

npm install toc-helper --save 
# или
yarn add toc-helper

2. Применение

2.1 `require`

const TocHelper = require('toc-helper')
new TocHelper(el [, options])

2.2 `import`

import TocHelper from 'toc-helper'
new TocHelper(el [, options])

2.3 Пример использования в `React`

2.3.1 Обычный режим

import TocHelper from 'toc-helper'
class App extends React.PureComponent{
  constructor(props){
    super(props)
    this.ref = null
  }
  componentDidMount(){
    new TocHelper(this.ref [, options])
  }
  render(){
    return <div ref={ref => this.ref = ref} />
  }
}

2.3.2 Режим хуков

import TocHelper from 'toc-helper'
export default App(){
 const ref = useRef()
 useEffect(()=>{
   new TocHelper(ref [, options])
 })
 return <div ref={ref} />
}

2.4 Пример использования в `vue` `v3`

<script>
  import TocHelper from 'toc-helper'
  setup(props, { emit }) {
    const toc = ref(null);
    let helper = null;
    onMounted(function () {
      helper = new TocHelper(toc [, options]);
    });

    return { toc };
  },
</script>
<template>
  <div ref="toc"></div>
</template>

2.5 Пример использования в `svelte`

<script>
  import TocHelper from 'toc-helper'
  let toc = null
  let helper = null
  onMount(function(){
    helper = new TocHelper(toc [, options])
  })
</script>
<div bind:this={toc}/>

3. API

`TocHelper(selector [, options])`

Конструктор метода, может быть создан только с помощью new.

selector
Тип: string | HTMLElement
Значение по умолчанию: нет
Обязательно: да

Если selector является строкой, он должен быть селектором, который можно получить с помощью document.querySelector, иначе будет выдана ошибка.

options
Тип: object | undefined
Значение по умолчанию: нет
Обязательно: необязательно

`reset`

Без параметров

Метод экземпляра, после вызова будет повторно проанализирован heading, если данные загружаются асинхронно, этот метод будет полезен.

`isEmpty`

Без параметров

Метод экземпляра, определяет, есть ли heading.

`syncScroll`

Без параметров

Метод экземпляра, синхронизирует прокрутку, скрывает и показывает, можно вызвать этот метод для синхронизации.

4. Конфигурация

`options`

1. `contentSelector`

Тип: string | HTMLElement
Значение по умолчанию: document.body

Если это строка, она должна быть селектором, который можно получить с помощью ducument.querySelector.

Анализирует содержимое каталога элементов.

2. `scrollSelector`

Тип: string | HTMLElement
Значение по умолчанию: document.body

Если это строка, то она должна быть селектором, который можно получить через ducument.querySelector.

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

3. `fixedSelector`

Тип: string | HTMLElement
Значение по умолчанию: каталог сам

Документ прокручивается до позиции этого селектора, и он фиксируется в верхней части.

4. `headingSelector`

Тип: string
Значение по умолчанию: h1, h2, h3, h4, h5, h6

Содержимое элемента анализируется с использованием всех каталогов.

Может быть не тегом h, но тег должен предоставлять атрибут data-level, чтобы указать текущий уровень каталога.

Конкретное использование — [contentSelector].querySelectorAll(headingSelector), поэтому необходимо правильно настроить contentSelector и headingSelector, иначе проанализированный каталог будет пустым.

5. `collapsedLevel`

Тип: number
Значение по умолчанию: 3

Каталоги выше этого уровня будут свернуты (скрыты) по умолчанию, и они будут автоматически развёрнуты при прокрутке до этой позиции или при нажатии на них, а затем снова свернутся.

6. `idPrefix`

Тип: string
Значение по умолчанию: bitoc-heading-

Префикс идентификатора каталога.

Влияет только на сам каталог, не влияет на содержание.

7. `levelClassPrefix`

Тип: string
Значение по умолчанию: bitoc-ml-

Смещение стиля уровня по умолчанию, уровень 2 каталога (bitoc-ml-2) смещается на 1rem, уровень 3 каталога (bitoc-ml-3) смещается на 2rem, и так далее; можно использовать стиль для изменения, имя стиля по умолчанию.

Уровень 1 каталога: bitoc-ml-1
Уровень 2 каталога: bitoc-ml-2
Уровень 3 каталога: bitoc-ml-3
Уровень 4 каталога: bitoc-ml-4
Уровень 5 каталога: bitoc-ml-5
Уровень 6 каталога: bitoc-ml-6

8. `scrollDuration`

Тип: number
Значение по умолчанию: 200

По умолчанию поддерживается прокрутка анимации, продолжительность анимации контролируется этим значением.

9. `scrollOffset`

Тип: number
Значение по умолчанию: 0

Величина смещения прокрутки.

Это значение относится только к содержимому, при щелчке по каталогу содержимое автоматически прокручивается в соответствующую позицию; если в верхней части содержимого есть фиксированный или абсолютный элемент позиционирования, позиция прокрутки будет иметь смещение, решение состоит из двух частей: Предположим, что фиксированная высота элемента позиционирования равна 64px:

Решение 1: используйте css, чтобы все заголовки padding-top были равны высоте заголовка, margin-top равны противоположному значению высоты заголовка; пример кода css выглядит следующим образом
```
[contentSelector] h1,
[contentSelector] h2,
[contentSelector] h3,
[contentSelector] h4,
```

... 10. fixedOffset

Тип: number | false Значение по умолчанию: динамическое вычисление

При достижении этой позиции каталог автоматически закрепляется в верхней части.

Это значение по умолчанию рассчитывается на основе элемента каталога [fixedSelector]. Если начальный каталог скрыт и весь документ прокручивается, то автоматически рассчитанное значение будет сильно отличаться. Поэтому рекомендуется указать это значение точно.
Если в верхней части есть элемент с фиксированной компоновкой, необходимо вычесть высоту элемента с фиксированной компоновкой. В противном случае может возникнуть значительное дрожание.
Если это значение равно false, функция закрепления будет отключена.

11. fixedClassName

Тип: string Значение по умолчанию: .bitoc-fixed

Стиль закрепления каталога в верхней части по умолчанию.

.bitoc-fixed{
  position: fixed !important;
}

12. beforeFixed

Тип: Function(isFixed: boolean) => false|void Значение по умолчанию: null

Функция-перехватчик перед закреплением каталога.

isFixed = true — закрепление. isFixed = false — отмена закрепления. Если возвращается false, операция закрепления отменяется, и afterFixed также не вызывается.

13. afterFixed

Тип: Function(isFixed: boolean) => void Значение по умолчанию: null

Функция-перехватчик после закрепления каталога.

isFixed = true — успешное закрепление. isFixed = false — успешная отмена закрепления.

Пять, дополнительные замечания

По умолчанию при закреплении каталога не указывается смещение top. Необходимо добавить соответствующий стиль. Например, если в верхней части имеется элемент с фиксированной компоновкой высотой 64 пикселя, необходимо добавить стиль:

.bitoc-fixed {
  top: 3.875rem;
}

Сам каталог не имеет ограничений по ширине. После закрепления каталог будет расширяться содержимым. Поэтому необходимо ограничить ширину закреплённого каталога. Пример:

 .bitoc-fixed {
    max-width: 27rem;
  }

Для обеспечения адаптивности пример:

 @media screen and (min-width: 1024px) and (max-width: 1216px) {
    #toc-box.bitoc-fixed {
      max-width: 19rem;
    }
  }

Каталог сам по себе не имеет ограничения по высоте. После закрепления содержимое может растянуть каталог за пределы экрана. Необходимо ограничить высоту каталога. Если каталог достигает этого предела, он автоматически прокручивается. Не нужно добавлять другие стили. Пример:

 .bitoc {
   max-height: 20.5rem;
}

Шесть, разработка

git clone https://github.com/itlangzi/toc-helper
cd toc-helper

Разработка среды

yarn dev --open

После выполнения команды перейдите по адресу http://localhost:3000/demo.

Сборка рабочей версии

yarn build

OSCHINA-MIRROR/itlangz-toc-helper

toc-helper

1. v2 функции

2. Использование

Браузер

npm

1. Установка

2. Применение

2.1 `require`

2.2 `import`

2.3 Пример использования в `React`

2.3.1 Обычный режим

2.3.2 Режим хуков

2.4 Пример использования в `vue` `v3`

2.5 Пример использования в `svelte`

3. API

`TocHelper(selector [, options])`

`reset`

`isEmpty`

`syncScroll`

4. Конфигурация

`options`

1. `contentSelector`

2. `scrollSelector`

3. `fixedSelector`

4. `headingSelector`

5. `collapsedLevel`

6. `idPrefix`

7. `levelClassPrefix`

8. `scrollDuration`

9. `scrollOffset`

Пять, дополнительные замечания

Шесть, разработка

Разработка среды

Сборка рабочей версии

Комментарии ( 0 )

Введение

Обновления (5)

Участники

Недавние действия

OSCHINA-MIRROR/itlangz-toc-helper .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

toc-helper

1. v2 функции

2. Использование

Браузер

npm

1. Установка

2. Применение

2.1 require

2.2 import

2.3 Пример использования в React

2.3.1 Обычный режим

2.3.2 Режим хуков

2.4 Пример использования в vue v3

2.5 Пример использования в svelte

3. API

TocHelper(selector [, options])

reset

isEmpty

syncScroll

4. Конфигурация

options

1. contentSelector

2. scrollSelector

3. fixedSelector

4. headingSelector

5. collapsedLevel

6. idPrefix

7. levelClassPrefix

8. scrollDuration

9. scrollOffset

Пять, дополнительные замечания

Шесть, разработка

Разработка среды

Сборка рабочей версии

Комментарии ( 0 )

Введение

Обновления (5)

Участники

Недавние действия

OSCHINA-MIRROR/itlangz-toc-helper

2.1 `require`

2.2 `import`

2.3 Пример использования в `React`

2.4 Пример использования в `vue` `v3`

2.5 Пример использования в `svelte`

`TocHelper(selector [, options])`

`reset`

`isEmpty`

`syncScroll`

`options`

1. `contentSelector`

2. `scrollSelector`

3. `fixedSelector`

4. `headingSelector`

5. `collapsedLevel`

6. `idPrefix`

7. `levelClassPrefix`

8. `scrollDuration`

9. `scrollOffset`