Часто задаваемые вопросы: что делать, если таблица не форматируется

Что вы узнаете

В этом уроке вы научитесь быстро диагностировать и решать распространенные проблемы при использовании плагина:

Находить причины, по которым таблицы не форматируются
Понимать значение ошибки «неверная структура таблицы»
Узнавать об известных ограничениях плагина и сценариях, где он не применим
Быстро проверять правильность конфигурации

Проблема 1: Таблица не форматируется автоматически

Симптомы

AI сгенерировал таблицу, но ширина столбцов неодинаковая, выравнивание отсутствует.

Возможные причины и решения

Причина 1: Плагин не настроен

Шаги проверки:

Откройте файл .opencode/opencode.jsonc
Убедитесь, что плагин присутствует в массиве plugin:

jsonc

{
  "plugin": ["@franlol/[email protected]"]
}

Если отсутствует, добавьте конфигурацию плагина
Перезапустите OpenCode, чтобы изменения вступили в силу

Формат конфигурации

Убедитесь, что версия и имя пакета указаны правильно, используя формат @franlol/opencode-md-table-formatter + @ + номер версии.

Причина 2: OpenCode не был перезапущен

Решение:

После добавления плагина необходимо полностью перезапустить OpenCode (не просто обновить страницу), чтобы плагин загрузился.

Причина 3: В таблице отсутствует разделительная строка

Пример симптома:

markdown

| Name | Age |
| Alice | 25 |
| Bob | 30 |

Такая таблица не будет отформатирована.

Решение:

Добавьте разделительную строку (вторая строка, в формате |---|):

markdown

| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |

Роль разделительной строки

Разделительная строка является стандартным синтаксисом Markdown-таблиц, используется для разделения заголовков и строк с содержимым, а также для указания выравнивания. Плагин обязан обнаружить разделительную строку, чтобы отформатировать таблицу.

Причина 4: Версия OpenCode устарела

Шаги проверки:

Откройте меню справки OpenCode
Просмотрите текущий номер версии
Убедитесь, что версия >= 1.0.137

Решение:

Обновитесь до последней версии OpenCode.

Требования к версии

Плагин использует хук experimental.text.complete, этот API доступен в OpenCode версии 1.0.137 и выше.

Проблема 2: Появляется комментарий "invalid structure"

Симптомы

В конце таблицы появляется:

markdown

<!-- table not formatted: invalid structure -->

Что означает «неверная структура таблицы»

Плагин выполняет проверку каждой Markdown-таблицы, только таблицы, прошедшие проверку, будут отформатированы. Если структура таблицы не соответствует спецификации, плагин сохранит исходный текст и добавит этот комментарий.

Распространенные причины

Причина 1: Недостаточное количество строк в таблице

Неверный пример:

markdown

| Name |

Только 1 строка, формат неполный.

Правильный пример:

markdown

| Name |
|---|

Требуется минимум 2 строки (включая разделительную строку).

Причина 2: Несовпадение количества столбцов

Неверный пример:

markdown

| Name | Age |
|--- | ---|
| Alice |

Первая строка содержит 2 столбца, вторая — 1 столбец, количество столбцов не совпадает.

Правильный пример:

markdown

| Name | Age |
|--- | ---|
| Alice | 25 |

Количество столбцов во всех строках должно быть одинаковым.

Причина 3: Отсутствие разделительной строки

Неверный пример:

markdown

| Name | Age |
| Alice | 25 |
| Bob | 30 |

Нет разделительной строки в формате |---|---|.

Правильный пример:

markdown

| Name | Age |
|--- | ---|
| Alice | 25 |
| Bob | 30 |

Как быстро диагностировать

Используйте следующий чек-лист:

[ ] В таблице минимум 2 строки
[ ] Количество столбцов одинаково во всех строках (посчитайте количество |)
[ ] Присутствует разделительная строка (обычно вторая строка в формате |---|)

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

Проблема 3: Появляется комментарий "table formatting failed"

Симптомы

В конце текста появляется:

markdown

<!-- table formatting failed: {сообщение об ошибке} -->

Причина

Это означает, что плагин сгенерировал неожиданное исключение.

Решение

Просмотрите сообщение об ошибке: часть {сообщение об ошибке} в комментарии объясняет конкретную проблему
Проверьте содержимое таблицы: убедитесь, что нет экстремальных особых случаев (например, сверхдлинная строка, специальная комбинация символов)
Сохраните исходный текст: даже при ошибке плагин не повредит исходный текст, ваше содержимое в безопасности
Сообщите о проблеме: если проблема повторяется, создайте отчет о проблеме в GitHub Issues

Изоляция ошибок

Плагин использует try-catch для обработки логики форматирования, даже при ошибке рабочий процесс OpenCode не будет прерван.

Проблема 4: Некоторые типы таблиц не поддерживаются

Неподдерживаемые типы таблиц

HTML-таблицы

Не поддерживаются:

html

<table>
  <tr><th>Name</th></tr>
  <tr><td>Alice</td></tr>
</table>

Поддерживаются только: Markdown-таблицы с разделителями (Pipe Table)

Многострочные ячейки

Не поддерживаются:

markdown

| Name | Description |
|--- | ---|
| Alice | Line 1<br>Line 2 |

Почему не поддерживаются

Плагин разработан для простых таблиц, генерируемых ИИ; многострочные ячейки требуют более сложной логики компоновки.

Таблицы без разделительной строки

Не поддерживаются:

markdown

| Name | Age |
| Alice | 25 |
| Bob | 30 |

Разделительная строка обязательна (см. «Причина 3» выше).

Проблема 5: Таблица по-прежнему невыровнена после форматирования

Возможные причины

Причина 1: Режим скрытия не включен

Плагин оптимизирован для режима скрытия (Concealment Mode) в OpenCode, который скрывает символы Markdown (такие как **, *).

Если в вашем редакторе не включен режим скрытия, таблица может выглядеть «невыровненной», потому что символы Markdown занимают реальную ширину.

Решение:

Убедитесь, что в OpenCode включен режим скрытия (включен по умолчанию).

Причина 2: Слишком длинное содержимое ячейки

Если содержимое ячейки очень длинное, таблица может сильно растянуться.

Это нормальное поведение, плагин не обрезает содержимое.

Причина 3: Символы в строковом коде

Символы Markdown в строковом коде (`**code**`) рассчитываются по их буквальной ширине, а не удаляются.

Пример:

| Символ | Ширина |
|--- | ---|
| Обычный текст | 4 |
| `**bold**` | 8 |

Это правильное поведение, потому что в режиме скрытия символы внутри блоков кода видимы.

Резюме урока

В этом уроке вы научились:

Диагностировать отсутствие форматирования: проверять конфигурацию, перезапускать, требования к версии, разделительные строки
Понимать ошибку неверной структуры: проверка количества строк, столбцов, наличия разделительной строки
Распознавать известные ограничения: не поддерживаются HTML-таблицы, многострочные ячейки, таблицы без разделительной строки
Быстрая самопроверка: использование чек-листа для проверки структуры таблиц

Проблема не решена?

Если вы проверили все вышеперечисленное, но проблема сохраняется:

Просмотрите полный журнал: плагин работает в фоновом режиме по умолчанию, подробного журнала нет
Создайте Issue: в GitHub Issues предоставьте пример вашей таблицы и сообщение об ошибке
Ознакомьтесь с продвинутыми курсами: прочитайте Спецификация таблиц и Принцип режима скрытия, чтобы узнать больше технических деталей

Анонс следующего урока

В следующем уроке мы изучим Известные ограничения: где проходят границы плагина.
Вы узнаете:
Дизайн-границы и ограничения плагина
Возможные будущие улучшения
Как определить, подходит ли данный сценарий для использования этого плагина

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть и просмотреть расположение исходного кода

Обновлено: 2026-01-26

Функция	Путь к файлу	Номера строк
Логика валидации таблиц	`index.ts`	70-88
Обнаружение строк таблицы	`index.ts`	58-61
Обнаружение разделительной строки	`index.ts`	63-68
Обработка ошибок	`index.ts`	15-20
Комментарий о неверной таблице	`index.ts`	44-47

Ключевые бизнес-правила:

isValidTable(): проверяет, что таблица содержит минимум 2 строки, все строки имеют одинаковое количество столбцов, присутствует разделительная строка (строки 70-88)
isSeparatorRow(): использует регулярное выражение /^\s*:?-+:?\s*$/ для обнаружения разделительной строки (строки 63-68)
Минимальная ширина столбца: 3 символа (строка 115)

Механизм обработки ошибок:

Основная функция обработки обернута в try-catch (строки 15-20)
Ошибка форматирования: сохраняется исходный текст + добавляется комментарий 
Ошибка валидации: сохраняется исходный текст + добавляется комментарий

Часто задаваемые вопросы: что делать, если таблица не форматируется ​

Что вы узнаете ​

Проблема 1: Таблица не форматируется автоматически ​

Симптомы ​

Возможные причины и решения ​

Причина 1: Плагин не настроен ​

Причина 2: OpenCode не был перезапущен ​

Причина 3: В таблице отсутствует разделительная строка ​

Причина 4: Версия OpenCode устарела ​

Проблема 2: Появляется комментарий "invalid structure" ​

Симптомы ​

Что означает «неверная структура таблицы» ​

Распространенные причины ​

Причина 1: Недостаточное количество строк в таблице ​

Причина 2: Несовпадение количества столбцов ​

Причина 3: Отсутствие разделительной строки ​

Как быстро диагностировать ​

Проблема 3: Появляется комментарий "table formatting failed" ​

Симптомы ​

Причина ​

Решение ​

Проблема 4: Некоторые типы таблиц не поддерживаются ​

Неподдерживаемые типы таблиц ​

HTML-таблицы ​

Многострочные ячейки ​

Таблицы без разделительной строки ​

Проблема 5: Таблица по-прежнему невыровнена после форматирования ​

Возможные причины ​

Причина 1: Режим скрытия не включен ​

Причина 2: Слишком длинное содержимое ячейки ​

Причина 3: Символы в строковом коде ​

Резюме урока ​

Проблема не решена? ​

Анонс следующего урока ​

Приложение: Справочник по исходному коду ​

Часто задаваемые вопросы: что делать, если таблица не форматируется

Что вы узнаете

Проблема 1: Таблица не форматируется автоматически

Симптомы

Возможные причины и решения

Причина 1: Плагин не настроен

Причина 2: OpenCode не был перезапущен

Причина 3: В таблице отсутствует разделительная строка

Причина 4: Версия OpenCode устарела

Проблема 2: Появляется комментарий "invalid structure"

Симптомы

Что означает «неверная структура таблицы»

Распространенные причины

Причина 1: Недостаточное количество строк в таблице

Причина 2: Несовпадение количества столбцов

Причина 3: Отсутствие разделительной строки

Как быстро диагностировать

Проблема 3: Появляется комментарий "table formatting failed"

Симптомы

Причина

Решение

Проблема 4: Некоторые типы таблиц не поддерживаются

Неподдерживаемые типы таблиц

HTML-таблицы

Многострочные ячейки

Таблицы без разделительной строки

Проблема 5: Таблица по-прежнему невыровнена после форматирования

Возможные причины

Причина 1: Режим скрытия не включен

Причина 2: Слишком длинное содержимое ячейки

Причина 3: Символы в строковом коде

Резюме урока

Проблема не решена?

Анонс следующего урока

Приложение: Справочник по исходному коду