mirror of https://github.com/Nikolay-Shirokov/cc-1c-skills.git synced 2026-06-10 08:04:56 +03:00

Files

T

Nick Shirokov b3dac25729 Add epf-add-help skill and help specification

New skill /epf-add-help creates built-in help files (Help.xml + HTML page)
for external data processors. Also adds IncludeHelpInContents to form
metadata if missing.

New spec docs/1c-help-spec.md documents the help file format, HTML
template, and help button integration on forms.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-07 22:13:47 +03:00

6.9 KiB

Raw Permalink Blame History

Встроенная справка внешней обработки 1С

Спецификация добавления встроенной справки (Help) к внешней обработке (EPF) в формате XML-выгрузки версии 2.17.

1. Структура файлов

<ИмяОбработки>/
    Ext/
        Help.xml                    # Метаданные справки (обязательно)
        Help/
            ru.html                 # HTML-страница справки на русском языке

Справка не регистрируется в ChildObjects корневого XML обработки — достаточно наличия файлов Help.xml и Help/<язык>.html в каталоге Ext/.

2. Help.xml — метаданные справки

Пространство имён: http://v8.1c.ru/8.3/xcf/extrnprops (то же, что у Template.xml).

<?xml version="1.0" encoding="UTF-8"?>
<Help xmlns="http://v8.1c.ru/8.3/xcf/extrnprops"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      version="2.17">
    <Page>ru</Page>
</Help>

Элемент <Page> указывает код языка. Имя файла страницы: <код_языка>.html. Может быть несколько элементов <Page> для разных языков.

3. HTML-страница справки

Формат: HTML 4.0 Transitional, кодировка UTF-8.

Минимальный шаблон

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link rel="stylesheet" type="text/css" href="v8help://service_book/service_style"/>
</head>
<body>
    Содержимое справки
</body>
</html>

Обязательные элементы head

Элемент	Назначение
`<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>`	Кодировка UTF-8
`<link rel="stylesheet" type="text/css" href="v8help://service_book/service_style"/>`	Стили справки 1С (протокол `v8help://`)

Поддерживаемая разметка

Стандартный HTML 4.0: <h1>..<h4>, <p>, <ul>, <ol>, <li>, <table>, <strong>, <em>, <a>, <br>, <pre> и др. Стили 1С автоматически форматируют заголовки и абзацы.

4. Метаданные формы — IncludeHelpInContents

В файле метаданных формы (Forms/<ИмяФормы>.xml) должен быть элемент:

<IncludeHelpInContents>false</IncludeHelpInContents>

Полный контекст в файле формы:

<Form uuid="...">
    <Properties>
        <Name>ОсновнаяФорма</Name>
        ...
        <FormType>Managed</FormType>
        <IncludeHelpInContents>false</IncludeHelpInContents>
        <UsePurposes>...</UsePurposes>
        <ExtendedPresentation/>
    </Properties>
</Form>

Значение false — справка не включается в общее оглавление справочной системы (стандартное поведение для внешних обработок).

5. Кнопка вызова справки на форме

Для вызова справки используется стандартная команда платформы Form.StandardCommand.Help.

Вариант А: кнопка в AutoCommandBar формы

Простейший способ — добавить кнопку в автокомандную панель формы (id="-1"):

<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
    <Autofill>false</Autofill>
    <ChildItems>
        <Button name="ФормаСправка" id="<свободный_id>">
            <Type>CommandBarButton</Type>
            <CommandName>Form.StandardCommand.Help</CommandName>
            <ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="<свободный_id>"/>
        </Button>
    </ChildItems>
</AutoCommandBar>

Кнопка появится на автокомандной панели формы (верхняя строка). Подходит для простых форм.

Вариант Б: кнопка в пользовательской CommandBar

Если форма не использует AutoCommandBar (задан Autofill=false, панель скрыта или пуста), кнопку справки можно разместить в произвольной <CommandBar> группе среди других пользовательских кнопок:

<CommandBar name="МояКоманднаяПанель" id="...">
    <Autofill>false</Autofill>
    <HorizontalStretch>false</HorizontalStretch>
    <ExtendedTooltip name="МояКоманднаяПанельExtendedTooltip" id="..."/>
    <ChildItems>
        <!-- Другие кнопки -->
        <Button name="КнопкаДействие" id="...">
            <Type>CommandBarButton</Type>
            <CommandName>Form.Command.МояКоманда</CommandName>
            ...
        </Button>
        <!-- Кнопка справки -->
        <Button name="ФормаСправка" id="<свободный_id>">
            <Type>CommandBarButton</Type>
            <CommandName>Form.StandardCommand.Help</CommandName>
            <ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="<свободный_id>"/>
        </Button>
    </ChildItems>
</CommandBar>

Для стандартной команды Help не нужно объявлять элемент в секции <Commands> — платформа предоставляет её автоматически.

Важно

<Type>CommandBarButton</Type> — кнопка должна быть типа CommandBarButton (внутри <CommandBar>)
Никакого обработчика в Module.bsl не требуется — Form.StandardCommand.Help обрабатывается платформой
Платформа сама найдёт Help.xml и откроет соответствующую HTML-страницу

6. Чек-лист добавления справки

Создать <ИмяОбработки>/Ext/Help.xml с указанием языка (<Page>ru</Page>)
Создать <ИмяОбработки>/Ext/Help/ru.html с содержимым справки
Убедиться что в Forms/<ИмяФормы>.xml есть <IncludeHelpInContents>false</IncludeHelpInContents>
Добавить кнопку Form.StandardCommand.Help в CommandBar или AutoCommandBar формы
Собрать EPF — проверить что справка открывается по кнопке

6.9 KiB Raw Permalink Blame History Unescape Escape