mirror of
https://github.com/Nikolay-Shirokov/cc-1c-skills.git
synced 2026-06-10 16:14:54 +03:00
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>
This commit is contained in:
Nick Shirokov
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: epf-add-help
|
||||
description: Добавить встроенную справку к внешней обработке 1С
|
||||
argument-hint: <ProcessorName>
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Glob
|
||||
- Grep
|
||||
---
|
||||
|
||||
# /epf-add-help — Добавление справки
|
||||
|
||||
Добавляет встроенную справку к обработке: файл метаданных `Help.xml`, HTML-страницу и при необходимости обновляет метаданные форм.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/epf-add-help <ProcessorName> [Lang] [SrcDir]
|
||||
```
|
||||
|
||||
| Параметр | Обязательный | По умолчанию | Описание |
|
||||
|---------------|:------------:|--------------|-------------------------------------|
|
||||
| ProcessorName | да | — | Имя обработки |
|
||||
| Lang | нет | `ru` | Код языка справки |
|
||||
| SrcDir | нет | `src` | Каталог исходников |
|
||||
|
||||
## Команда
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -File .claude/skills/epf-add-help/scripts/add-help.ps1 -ProcessorName "<ProcessorName>" [-Lang "<Lang>"] [-SrcDir "<SrcDir>"]
|
||||
```
|
||||
|
||||
## Что создаётся
|
||||
|
||||
```
|
||||
<SrcDir>/<ProcessorName>/
|
||||
Ext/
|
||||
Help.xml # Метаданные справки (namespace extrnprops)
|
||||
Help/
|
||||
ru.html # HTML-страница справки
|
||||
```
|
||||
|
||||
- `Help.xml` — фиксированная структура с `<Page>ru</Page>` (namespace `http://v8.1c.ru/8.3/xcf/extrnprops`)
|
||||
- `ru.html` — HTML 4.0 Transitional с подключением стилей 1С (`v8help://service_book/service_style`)
|
||||
- Справка **не регистрируется** в `ChildObjects` корневого XML — достаточно наличия файлов
|
||||
|
||||
## Что модифицируется
|
||||
|
||||
- Если в метаданных формы (`Forms/<FormName>.xml`) отсутствует `<IncludeHelpInContents>` — скрипт добавит `<IncludeHelpInContents>false</IncludeHelpInContents>` после `<FormType>`. Для форм, созданных через `/epf-add-form`, элемент уже есть.
|
||||
|
||||
## Кнопка справки на форме
|
||||
|
||||
После создания справки для её вызова нужна кнопка на форме. Добавь кнопку `Form.StandardCommand.Help` в AutoCommandBar формы (`Forms/<FormName>/Ext/Form.xml`).
|
||||
|
||||
### Текущая структура AutoCommandBar (созданная epf-add-form)
|
||||
|
||||
```xml
|
||||
<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
|
||||
<Autofill>true</Autofill>
|
||||
</AutoCommandBar>
|
||||
```
|
||||
|
||||
### Нужно заменить на
|
||||
|
||||
```xml
|
||||
<AutoCommandBar name="ФормаКоманднаяПанель" id="-1">
|
||||
<Autofill>true</Autofill>
|
||||
<ChildItems>
|
||||
<Button name="ФормаСправка" id="{{свободный_id}}">
|
||||
<Type>CommandBarButton</Type>
|
||||
<CommandName>Form.StandardCommand.Help</CommandName>
|
||||
<ExtendedTooltip name="ФормаСправкаExtendedTooltip" id="{{свободный_id + 1}}"/>
|
||||
</Button>
|
||||
</ChildItems>
|
||||
</AutoCommandBar>
|
||||
```
|
||||
|
||||
### Выбор id
|
||||
|
||||
Просмотри все `id="..."` в `Form.xml` и выбери следующий свободный числовой id. Обычно id начинаются с 1 и идут подряд. Для кнопки нужны 2 id: один для Button, один для ExtendedTooltip.
|
||||
|
||||
### Важно
|
||||
|
||||
- `Form.StandardCommand.Help` — стандартная команда платформы, не нужно объявлять в `<Commands>`
|
||||
- Обработчика в Module.bsl не требуется — платформа сама найдёт `Help.xml` и откроет HTML
|
||||
|
||||
## Редактирование справки
|
||||
|
||||
После создания содержимое справки — обычный HTML. Отредактируй `Ext/Help/ru.html` в соответствии с назначением обработки. Поддерживается стандартная HTML-разметка: `<h1>`..`<h4>`, `<p>`, `<ul>`, `<ol>`, `<table>`, `<strong>`, `<em>`, `<a>`, `<pre>`.
|
||||
|
||||
## Спецификация
|
||||
|
||||
Подробности формата: `docs/1c-help-spec.md`
|
||||
@@ -0,0 +1,115 @@
|
||||
param(
|
||||
[Parameter(Mandatory)]
|
||||
[string]$ProcessorName,
|
||||
|
||||
[string]$Lang = "ru",
|
||||
|
||||
[string]$SrcDir = "src"
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
# --- Проверки ---
|
||||
|
||||
$processorDir = Join-Path $SrcDir $ProcessorName
|
||||
$extDir = Join-Path $processorDir "Ext"
|
||||
|
||||
if (-not (Test-Path $extDir)) {
|
||||
Write-Error "Каталог обработки не найден: $extDir. Сначала выполните epf-init."
|
||||
exit 1
|
||||
}
|
||||
|
||||
$helpXmlPath = Join-Path $extDir "Help.xml"
|
||||
if (Test-Path $helpXmlPath) {
|
||||
Write-Error "Справка уже существует: $helpXmlPath"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# --- Кодировка ---
|
||||
|
||||
$encBom = New-Object System.Text.UTF8Encoding($true)
|
||||
|
||||
# --- 1. Help.xml ---
|
||||
|
||||
$helpXml = @"
|
||||
<?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>$Lang</Page>
|
||||
</Help>
|
||||
"@
|
||||
|
||||
[System.IO.File]::WriteAllText($helpXmlPath, $helpXml, $encBom)
|
||||
|
||||
# --- 2. Help/<lang>.html ---
|
||||
|
||||
$helpDir = Join-Path $extDir "Help"
|
||||
New-Item -ItemType Directory -Path $helpDir -Force | Out-Null
|
||||
|
||||
$helpHtmlPath = Join-Path $helpDir "$Lang.html"
|
||||
|
||||
$helpHtml = @"
|
||||
<!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>
|
||||
<h1>$ProcessorName</h1>
|
||||
<p>Описание обработки.</p>
|
||||
</body>
|
||||
</html>
|
||||
"@
|
||||
|
||||
[System.IO.File]::WriteAllText($helpHtmlPath, $helpHtml, $encBom)
|
||||
|
||||
# --- 3. Проверка IncludeHelpInContents в метаданных форм ---
|
||||
|
||||
$formsDir = Join-Path $processorDir "Forms"
|
||||
if (Test-Path $formsDir) {
|
||||
$formMetaFiles = Get-ChildItem -Path $formsDir -Filter "*.xml" -File
|
||||
foreach ($formMeta in $formMetaFiles) {
|
||||
$xmlDoc = New-Object System.Xml.XmlDocument
|
||||
$xmlDoc.PreserveWhitespace = $true
|
||||
$xmlDoc.Load($formMeta.FullName)
|
||||
|
||||
$nsMgr = New-Object System.Xml.XmlNamespaceManager($xmlDoc.NameTable)
|
||||
$nsMgr.AddNamespace("md", "http://v8.1c.ru/8.3/MDClasses")
|
||||
|
||||
$includeHelp = $xmlDoc.SelectSingleNode("//md:IncludeHelpInContents", $nsMgr)
|
||||
if (-not $includeHelp) {
|
||||
# Добавить после <FormType>
|
||||
$formType = $xmlDoc.SelectSingleNode("//md:FormType", $nsMgr)
|
||||
if ($formType) {
|
||||
$newElem = $xmlDoc.CreateElement("IncludeHelpInContents", "http://v8.1c.ru/8.3/MDClasses")
|
||||
$newElem.InnerText = "false"
|
||||
$parent = $formType.ParentNode
|
||||
$nextSibling = $formType.NextSibling
|
||||
# Вставить перенос + табуляцию + элемент
|
||||
$ws = $xmlDoc.CreateWhitespace("`n`t`t`t")
|
||||
if ($nextSibling) {
|
||||
$parent.InsertBefore($ws, $nextSibling) | Out-Null
|
||||
$parent.InsertBefore($newElem, $ws) | Out-Null
|
||||
} else {
|
||||
$parent.AppendChild($ws) | Out-Null
|
||||
$parent.AppendChild($newElem) | Out-Null
|
||||
}
|
||||
|
||||
$settings = New-Object System.Xml.XmlWriterSettings
|
||||
$settings.Encoding = $encBom
|
||||
$settings.Indent = $false
|
||||
$stream = New-Object System.IO.FileStream($formMeta.FullName, [System.IO.FileMode]::Create)
|
||||
$writer = [System.Xml.XmlWriter]::Create($stream, $settings)
|
||||
$xmlDoc.Save($writer)
|
||||
$writer.Close()
|
||||
$stream.Close()
|
||||
|
||||
Write-Host " IncludeHelpInContents добавлен: $($formMeta.Name)"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "[OK] Создана справка: $ProcessorName"
|
||||
Write-Host " Метаданные: $helpXmlPath"
|
||||
Write-Host " Страница: $helpHtmlPath"
|
||||
@@ -9,6 +9,7 @@
|
||||
| `/epf-init` | `<Name> [Synonym]` | Создать новую обработку (корневой XML + модуль объекта) |
|
||||
| `/epf-add-form` | `<ProcessorName> <FormName> [Synonym]` | Добавить управляемую форму |
|
||||
| `/epf-add-template` | `<ProcessorName> <TemplateName> <TemplateType>` | Добавить макет (HTML, Text, SpreadsheetDocument, BinaryData) |
|
||||
| `/epf-add-help` | `<ProcessorName>` | Добавить встроенную справку (Help.xml + HTML) |
|
||||
| `/epf-remove-form` | `<ProcessorName> <FormName>` | Удалить форму |
|
||||
| `/epf-remove-template` | `<ProcessorName> <TemplateName>` | Удалить макет |
|
||||
| `/epf-build` | `<ProcessorName>` | Собрать EPF из XML (документация команды 1cv8.exe) |
|
||||
@@ -97,16 +98,19 @@ src/
|
||||
├── epf-remove-template/ # SKILL.md + scripts/remove-template.ps1
|
||||
├── epf-build/ # SKILL.md (только документация)
|
||||
├── epf-dump/ # SKILL.md (только документация)
|
||||
├── epf-add-help/ # SKILL.md + scripts/add-help.ps1
|
||||
├── epf-bsp-init/ # SKILL.md (шаблоны кода, без скриптов)
|
||||
└── epf-bsp-add-command/ # SKILL.md (шаблоны кода, без скриптов)
|
||||
docs/
|
||||
├── 1c-xml-format-spec.md # Спецификация XML-формата выгрузки
|
||||
├── 1c-help-spec.md # Спецификация встроенной справки
|
||||
└── build-spec.md # Спецификация команд сборки/разборки
|
||||
```
|
||||
|
||||
## Спецификации
|
||||
|
||||
- [XML-формат выгрузки обработок](docs/1c-xml-format-spec.md) — полное описание структуры XML-файлов, namespace'ов, элементов форм
|
||||
- [Встроенная справка](docs/1c-help-spec.md) — Help.xml, HTML-страницы, кнопка справки на форме
|
||||
- [Сборка и разборка EPF](docs/build-spec.md) — команды `1cv8.exe`, параметры, коды возврата
|
||||
|
||||
## Технические детали
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
# Встроенная справка внешней обработки 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
|
||||
<?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.
|
||||
|
||||
### Минимальный шаблон
|
||||
|
||||
```html
|
||||
<!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`) должен быть элемент:
|
||||
|
||||
```xml
|
||||
<IncludeHelpInContents>false</IncludeHelpInContents>
|
||||
```
|
||||
|
||||
Полный контекст в файле формы:
|
||||
|
||||
```xml
|
||||
<Form uuid="...">
|
||||
<Properties>
|
||||
<Name>ОсновнаяФорма</Name>
|
||||
...
|
||||
<FormType>Managed</FormType>
|
||||
<IncludeHelpInContents>false</IncludeHelpInContents>
|
||||
<UsePurposes>...</UsePurposes>
|
||||
<ExtendedPresentation/>
|
||||
</Properties>
|
||||
</Form>
|
||||
```
|
||||
|
||||
Значение `false` — справка не включается в общее оглавление справочной системы (стандартное поведение для внешних обработок).
|
||||
|
||||
## 5. Кнопка вызова справки на форме
|
||||
|
||||
Для вызова справки используется стандартная команда платформы `Form.StandardCommand.Help`.
|
||||
|
||||
### Вариант А: кнопка в AutoCommandBar формы
|
||||
|
||||
Простейший способ — добавить кнопку в автокомандную панель формы (`id="-1"`):
|
||||
|
||||
```xml
|
||||
<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>` группе среди других пользовательских кнопок:
|
||||
|
||||
```xml
|
||||
<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. Чек-лист добавления справки
|
||||
|
||||
1. Создать `<ИмяОбработки>/Ext/Help.xml` с указанием языка (`<Page>ru</Page>`)
|
||||
2. Создать `<ИмяОбработки>/Ext/Help/ru.html` с содержимым справки
|
||||
3. Убедиться что в `Forms/<ИмяФормы>.xml` есть `<IncludeHelpInContents>false</IncludeHelpInContents>`
|
||||
4. Добавить кнопку `Form.StandardCommand.Help` в CommandBar или AutoCommandBar формы
|
||||
5. Собрать EPF — проверить что справка открывается по кнопке
|
||||
@@ -10,6 +10,9 @@
|
||||
<ИмяОбработки>/
|
||||
Ext/
|
||||
ObjectModule.bsl # Модуль объекта (опционально)
|
||||
Help.xml # Метаданные справки (опционально)
|
||||
Help/
|
||||
ru.html # HTML-страница справки
|
||||
Forms/
|
||||
<ИмяФормы>.xml # Метаданные формы
|
||||
<ИмяФормы>/
|
||||
@@ -28,6 +31,7 @@
|
||||
- 0..N форм (каталог `Forms/`)
|
||||
- 0..N макетов (каталог `Templates/`)
|
||||
- 0..1 модуль объекта (`Ext/ObjectModule.bsl`)
|
||||
- 0..1 встроенная справка (`Ext/Help.xml` + `Ext/Help/<язык>.html`), см. [1c-help-spec.md](1c-help-spec.md)
|
||||
- 0..N табличных частей (описаны в корневом XML)
|
||||
|
||||
## 2. Пространства имён XML
|
||||
|
||||
Reference in New Issue
Block a user