Skip to content

darkClaw921/bitrix24-help-developer

BranchesTags

Repository files navigation

Bitrix24 Help Developer

Web Extension для Safari (macOS) и Google Chrome, которое помогает разработчикам Битрикс24 быстро получать ID полей сущностей при работе с CRM и другими модулями.

Возможности

🎯 Основной функционал

  • Автоматическое обнаружение полей — расширение автоматически находит все поля сущностей Битрикс24 на странице
  • Показ ID при наведении — при наведении курсора на поле появляется тултип с его ID
  • Копирование ID одним кликом — клик по тултипу копирует ID в буфер обмена
  • Работа с динамическим контентом — автоматически обрабатывает поля, загружаемые через AJAX
  • Поддержка iframe — работает даже если форма находится внутри iframe

📋 Расширенные возможности для списочных полей

Для полей типа enumeration (список) и select доступны дополнительные функции:

  • Показ всех значений — тултип отображает ID поля и все доступные значения с их ID
  • Копирование в JSON формате — генерация JSON объекта с транслитерированными ключами
  • Копирование в Python dataclass — генерация Python класса с транслитерацией

⚙️ Управление

  • Включение/выключение — переключатель в popup для временного отключения расширения
  • Сохранение состояния — настройки сохраняются между сессиями

Установка

Safari (macOS)

  1. Откройте проект в Xcode
  2. Соберите проект (⌘+B)
  3. Запустите приложение (⌘+R)
  4. В Safari перейдите в Настройки → Расширения
  5. Включите расширение "bitrix24-help-developer Extension"
  6. Разрешите доступ к нужным сайтам

Google Chrome

  1. Откройте Chrome и перейдите в chrome://extensions/
  2. Включите режим разработчика (Developer mode) в правом верхнем углу
  3. Нажмите Загрузить распакованное расширение (Load unpacked)
  4. Выберите папку bitrix24-help-developer Chrome Extension/Resources
  5. Расширение будет установлено и готово к использованию

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

Базовое использование

  1. Откройте любую страницу Битрикс24 с формами редактирования сущностей (CRM, Сделки, Контакты и т.д.)
  2. Наведите курсор на любое поле формы
  3. Появится тултип с ID поля
  4. Кликните по тултипу, чтобы скопировать ID в буфер обмена

Пример:

При наведении на поле "Название сделки":
┌─────────────────┐
│ 📋 TITLE        │  ← ID поля
└─────────────────┘

После клика: "TITLE" скопировано в буфер обмена

Работа со списочными полями

Для полей типа список (например, "Статус", "Тип сделки") расширение показывает дополнительную информацию:

Пример тултипа для списочного поля:

┌─────────────────────────────┐
│ 📋 STATUS                    │  ← ID поля
│ NEW: Новая                  │  ← ID значения: Текст
│ PREPARATION: Приоритизация  │
│ PREPAYMENT_INVOICE: Счет    │
│ EXECUTING: В работе         │
│ FINALIZED: Завершена        │
│ SUCCESS: Успешно реализована│
│ LOSE: Проиграна             │
│                             │
│ [JSON] [Python]             │  ← Кнопки копирования
└─────────────────────────────┘

Копирование в JSON формате

Кнопка JSON генерирует объект с транслитерированными ключами:

Пример результата:

{
  "NEW": "NEW"  // Новая
  "PREPARATION": "PREPARATION"  // Приоритизация
  "PREPAYMENT_INVOICE": "PREPAYMENT_INVOICE"  // Счет
  "EXECUTING": "EXECUTING"  // В работе
  "FINALIZED": "FINALIZED"  // Завершена
  "SUCCESS": "SUCCESS"  // Успешно реализована
  "LOSE": "LOSE"  // Проиграна
}

Использование в коде:

const STATUS = {
  "NEW": "NEW",
  "PREPARATION": "PREPARATION",
  "EXECUTING": "EXECUTING",
  // ...
};

// Использование
BX24.callMethod('crm.deal.update', {
  id: 123,
  fields: {
    STATUS: STATUS.NEW
  }
});

Копирование в Python dataclass формате

Кнопка Python генерирует Python dataclass класс:

Пример результата:

@dataclass
class Status:
    ID: str = "STATUS"
    NEW: str = "NEW"  # Новая
    PREPARATION: str = "PREPARATION"  # Приоритизация
    PREPAYMENT_INVOICE: str = "PREPAYMENT_INVOICE"  # Счет
    EXECUTING: str = "EXECUTING"  # В работе
    FINALIZED: str = "FINALIZED"  # Завершена
    SUCCESS: str = "SUCCESS"  # Успешно реализована
    LOSE: str = "LOSE"  # Проиграна

Использование в коде:

from dataclasses import dataclass

@dataclass
class Status:
    ID: str = "STATUS"
    NEW: str = "NEW"  # Новая
    PREPARATION: str = "PREPARATION"  # Приоритизация
    # ...

# Использование
deal_data = {
    'id': 123,
    'fields': {
        'STATUS': Status.NEW
    }
}

Примечание: Если название поля не найдено, используется транслитерированный ID поля в качестве имени класса.

Позиционирование тултипа

Тултип позиционируется относительно элемента поля (не курсора), что позволяет навести на него курсор для клика:

  • Позиционирование всегда слева от элемента поля
  • Смещение на 12px от границы элемента
  • Автоматическая корректировка по вертикали: если не помещается снизу — отображается сверху
  • Минимальные отступы 10px от краев viewport

Управление расширением

  1. Кликните на иконку расширения в панели инструментов Safari
  2. Используйте переключатель для включения/выключения расширения
  3. Статус отображается под переключателем ("Включено" / "Выключено")

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

Пример 1: Получение ID поля "Название"

  1. Откройте форму редактирования сделки в Битрикс24
  2. Наведите курсор на поле "Название"
  3. В тултипе увидите: TITLE
  4. Кликните по тултипу
  5. ID TITLE скопирован в буфер обмена

Пример 2: Работа со статусами сделки

  1. Наведите курсор на поле "Статус"
  2. В тултипе увидите: 
    STATUS
NEW: Новая
PREPARATION: Приоритизация
EXECUTING: В работе
...
  3. Кликните кнопку JSON для копирования в JSON формате
  4. Или кликните кнопку Python для копирования в Python dataclass формате

Пример 3: Использование в REST API

// Получили ID поля через расширение: "TITLE"
BX24.callMethod('crm.deal.update', {
    id: 123,
    fields: {
        TITLE: 'Новая сделка'
    }
});

Пример 4: Использование в Python

# Получили Python dataclass через расширение
from dataclasses import dataclass

@dataclass
class Status:
    ID: str = "STATUS"
    NEW: str = "NEW"
    # ...

# Использование в запросе
import requests

response = requests.post(
    f'{bitrix_url}/rest/crm.deal.update',
    json={
        'id': 123,
        'fields': {
            'STATUS': Status.NEW
        }
    }
)

Поддерживаемые типы полей

  • ✅ Текстовые поля (text, string)
  • ✅ Числовые поля (integer, double)
  • ✅ Дата и время (date, datetime)
  • ✅ Списочные поля (enumeration, select) — с расширенными возможностями
    • Обычные <select> элементы
    • Элементы с атрибутом data-items (JSON массив)
    • Popup-списки с data-item атрибутами
    • UI Selector Dialog элементы
  • ✅ Множественный выбор (multiselect)
  • ✅ Пользовательские поля (custom) — включая поля в формате USER_FIELDS[ID]
  • ✅ Канбан-колонки — элементы с классом .main-kanban-column-body

Технические детали

Как работает обнаружение полей

Расширение использует несколько стратегий для обнаружения полей:

  1. Основной селектор: .ui-entity-editor-content-block[data-cid] — стандартные поля редактора сущностей
  2. Альтернативный селектор: элементы с атрибутом data-field-tag внутри блоков редактора
  3. Пользовательские поля: элементы с классом .tasks-uf-panel-row, .js-id-item-set-item или содержащие инпут с атрибутом name в формате USER_FIELDS[ID]
  4. Канбан-колонки: элементы с классом .main-kanban-column-body и атрибутом data-id
  5. Автоматическое отслеживание: динамически добавляемые поля через MutationObserver

Извлечение ID

Приоритет извлечения ID:

  1. data-cid — основной атрибут (наивысший приоритет)
  2. data-field-tag — запасной вариант для полей редактора
  3. Атрибут name инпута в формате USER_FIELDS[ID] — для пользовательских полей (ID извлекается из скобок)
  4. data-id — для канбан-колонок

Транслитерация

Расширение автоматически транслитерирует русские названия полей и значений в латиницу для использования в:

  • Ключах JSON объектов
  • Именах классов Python
  • Именах параметров Python

Примеры транслитерации:

  • "Статус" → "Status"
  • "Новая" → "Novaya"
  • "В работе" → "V_rabote"

Обработка динамического контента

Расширение автоматически обрабатывает поля, загружаемые через AJAX:

  • MutationObserver отслеживает добавление новых элементов в DOM
  • При обнаружении новых полей автоматически добавляются обработчики событий
  • Проверка выполняется с задержкой для оптимизации производительности

Ограничения

  • Safari: Работает только в Safari на macOS (требует macOS приложение-обертку)
  • Chrome: Работает в Google Chrome и других браузерах на базе Chromium
  • Требует разрешения на доступ к сайтам Битрикс24
  • Для работы с iframe требуется, чтобы iframe был доступен (не cross-origin)
  • Расширение работает на всех страницах (<all_urls>), но функциональность активируется только на страницах с формами Битрикс24

Разработка

Структура проекта

bitrix24-help-developer/
├── bitrix24-help-developer/                    # macOS приложение-обертка для Safari
│   ├── AppDelegate.swift                        # Точка входа приложения
│   ├── ViewController.swift                     # Управление окном и взаимодействие с Safari Extension API
│   ├── Assets.xcassets/                         # Ресурсы приложения (иконки, цвета)
│   ├── Base.lproj/                              # Локализованные ресурсы
│   └── Resources/                               # HTML/CSS/JS ресурсы для окна приложения
│       ├── Main.html                            # HTML интерфейса окна приложения
│       ├── Script.js                            # JavaScript логика окна приложения
│       └── Style.css                            # Стили окна приложения
│
├── bitrix24-help-developer Extension/          # Safari Web Extension
│   ├── SafariWebExtensionHandler.swift          # Обработчик нативных сообщений
│   ├── Info.plist                               # Конфигурация расширения для macOS
│   └── Resources/
│       ├── manifest.json                         # Конфигурация расширения (WebExtensions API)
│       ├── content.js                           # Основная логика обнаружения полей и показа ID
│       ├── background.js                        # Background script для обработки событий
│       ├── popup.html/js/css                    # Интерфейс popup расширения
│       ├── tooltip.css                          # Стили тултипа с ID полей
│       ├── images/                              # Иконки расширения различных размеров
│       └── _locales/                            # Локализация
│           └── en/messages.json                 # Тексты интерфейса на английском
│
├── bitrix24-help-developer Chrome Extension/    # Chrome Web Extension
│   └── Resources/
│       ├── manifest.json                         # Конфигурация расширения (Chrome MV3)
│       ├── background.js                        # Service worker для обработки событий
│       ├── content.js                           # Основная логика обнаружения полей и показа ID
│       ├── popup.html/js/css                    # Интерфейс popup расширения
│       ├── tooltip.css                          # Стили тултипа с ID полей
│       ├── images/                              # Иконки расширения различных размеров
│       └── _locales/                            # Локализация
│           └── en/messages.json                 # Тексты интерфейса на английском
│
└── bitrix24-help-developer.xcodeproj/          # Xcode проект

Сборка

Safari Extension

# Откройте проект в Xcode
open bitrix24-help-developer.xcodeproj

# Или соберите через командную строку
xcodebuild -project bitrix24-help-developer.xcodeproj -scheme bitrix24-help-developer

Chrome Extension

Chrome Extension не требует сборки — это готовые файлы в папке bitrix24-help-developer Chrome Extension/Resources. Для разработки:

  1. Внесите изменения в файлы расширения
  2. В Chrome перейдите в chrome://extensions/
  3. Нажмите кнопку обновления (🔄) на карточке расширения
  4. Изменения применятся автоматически

Поддержка

При возникновении проблем:

Safari

  1. Проверьте, что расширение включено в настройках Safari (Настройки → Расширения)
  2. Убедитесь, что расширение имеет доступ к нужным сайтам
  3. Проверьте консоль разработчика Safari (⌥⌘C) на наличие ошибок
  4. Убедитесь, что вы находитесь на странице с формами Битрикс24
  5. Перезапустите приложение-обертку, если расширение не работает

Chrome

  1. Проверьте, что расширение включено в chrome://extensions/
  2. Убедитесь, что расширение имеет доступ к нужным сайтам (проверьте разрешения)
  3. Проверьте консоль разработчика (F12) на наличие ошибок
  4. Убедитесь, что вы находитесь на странице с формами Битрикс24
  5. Попробуйте перезагрузить страницу после установки расширения

Лицензия

[Укажите лицензию проекта]

Авторы

[Укажите авторов проекта]

About

Web Extension для Safari (macOS) и Google Chrome, которое помогает разработчикам Битрикс24 быстро получать ID полей сущностей при работе с CRM и другими модулями.

Topics

extension bitrix24 b24

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages