Импорт функций

Узнайте, как импортировать функции из других плагинов, написанных на разных языках, и использовать их в своем собственном.

В Plugify языковой модуль JavaScript позволяет импортировать и использовать функции из плагинов, написанных на других языках. Это достигается за счет синтетических модулей, генерируемых во время выполнения, которые обеспечивают бесшовное взаимодействие между плагинами. Кроме того, файлы типов (.d.ts) могут использоваться для предоставления информации о типах TypeScript для улучшения опыта разработки в IDE, таких как VSCode.

Это руководство объясняет, как импортировать функции в JavaScript и как использовать файлы типов для разработки.

Обзор

При импорте функций из другого плагина в JavaScript:

  1. Модули, генерируемые во время выполнения: Plugify динамически генерирует синтетические модули во время выполнения, позволяя вам импортировать и вызывать функции из других плагинов напрямую.
  2. Файлы типов для разработки: Файлы типов (.d.ts) предоставляют информацию о типах TypeScript для JavaScript API. Эти файлы не требуются для выполнения во время выполнения, но полезны для разработки.
  3. Прямые вызовы функций: Функции вызываются напрямую с использованием импортированных синтетических модулей.

Импорт функций в JavaScript

Импорт синтетических модулей

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

plugin.mjs
import { Plugin, Vector2, Vector3, Vector4, Matrix4x4 } from 'plugify';
import * as master from ':plugin_from_another_language';
  • plugify: Основной модуль Plugify, предоставляющий служебные классы, такие как Vector2, Vector3 и т.д.
  • plugin_from_another_language: Синтетический модуль для целевого плагина. Замените это на имя плагина, из которого вы хотите импортировать функции.

Вызов импортированных функций

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

Пример 1: Вызов простой функции

plugin.mjs
export const func = () => {
    master.ParamCallback(
        111, 
        2.2, 
        5.1234, 
        new Vector4(-125.1, -225.2, -325.3, -425.4), 
        [60000000, -700000000, 80000000000], 
        'D', 
        'pink metal', 
        'Y', 
        -100
    );
};
  • ParamCallback: Это пример функции, экспортируемой целевым плагином. Замените его на фактическое имя функции.
  • Параметры: Передайте необходимые параметры, как определено в сигнатуре функции.

Пример 2: Вызов функции с параметром-обратным вызовом

Если импортируемая функция требует обратный вызов в качестве параметра, вы можете определить обратный вызов в JavaScript и передать его функции. Вот пример:

plugin.mjs
export class CallbackHolder {
    static mockFunc(u32, v3, u_vec) {
        // Изменить параметры (переданные по ссылке)
        u32 = 42;
        v3 = new Vector3(1.0, 2.0, 3.0);
        u_vec = [1, 2, 3];
        // Вернуть измененные значения в массиве
        return [null, u32, v3, u_vec];
    }
}

export const func_call = () => {
    const result = master.CallFuncCallback(CallbackHolder.mockFunc);
    return result;
};
  • CallFuncCallback: Это пример функции, которая принимает обратный вызов в качестве параметра.
  • mockFunc: Это функция обратного вызова, определенная в JavaScript. Она изменяет параметры, переданные по ссылке, и возвращает их в массиве.
  • Возвращаемые значения: Функция обратного вызова возвращает null (для типа возвращаемого значения void) и измененные параметры.

Использование файлов типов для разработки

Файлы типов (.d.ts) не требуются для выполнения во время выполнения, но настоятельно рекомендуются для разработки. Они предоставляют информацию о типах TypeScript, что облегчает понимание доступных функций и их параметров.

Генерация файлов типов

Plugify предоставляет скрипт generator.js для автоматической генерации файлов типов для импортируемых плагинов.

Найдите скрипт генератора:

  • Скрипт generator.py находится в папке generator языкового модуля JavaScript.

Запустите скрипт генератора:

  • Откройте терминал или командную строку и перейдите в папку, содержащую generator.js.
  • Запустите скрипт с помощью следующей команды:
    node generator.js "путь_к_плагину.pplugin" "выходная_папка"
    
    • путь_к_плагину.pplugin: Путь к файлу манифеста плагина (.pplugin), из которого вы хотите импортировать функции.
    • выходная_папка: Каталог, в котором будет сохранен сгенерированный файл типов.

Пример:

python generator.py ./plugins/MyPlugin/MyPlugin.pplugin ./types/

Сгенерированный файл типов:

  • Скрипт сгенерирует файл типов (например, MyPlugin.d.ts) в указанной выходной папке.
  • Пример содержимого файла типов:
    MyPlugin.d.ts
    import { Vector2, Vector3, Vector4, Matrix4x4 } from 'plugify';
    
    declare module ':cross_call_master' {
        export function ParamCallback(
            a: number, 
            b: number, 
            c: number, 
            d: Vector4, 
            e: number[], 
            f: string, 
            g: string, 
            h: string, 
            k: number
        ): void;
    
        export type Func = (u32: number, vec3: Vector3, vecU32: number[]) => [void,number,Vector3,number[]];
        export function CallFuncCallback(callback: Func): string;
    }
    

Использование файлов типов в вашей IDE:

  • Поместите сгенерированный файл типов (.d.ts) в каталог вашего проекта (но не в папку с плагинами).
  • IDE, такие как VSCode, будут использовать файл типов для предоставления подсказок по типам и автодополнения.

Поддержка VSCode:

  • VSCode автоматически обнаруживает файлы типов в вашем проекте. Убедитесь, что папка types (или папка, содержащая ваши файлы .d.ts) включена в ваш файл tsconfig.json или jsconfig.json.
  • Пример конфигурации tsconfig.json:
    {
        "compilerOptions": {
            "typeRoots": ["./types"]
        }
    }
    

Примечания

  • Файлы типов необязательны: Файлы типов предназначены только для разработки и не должны включаться в папку выполнения вашего плагина.
  • Эффективность во время выполнения: Поскольку JavaScript является динамически типизированным, вызовы функций разрешаются во время выполнения без необходимости предварительно скомпилированных заголовков или определений типов.

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