Directus自定义流程操作组件开发指南

概述

在使用Directus进行流程(Flow)扩展开发时，开发者可能会遇到自定义操作组件(OperationComponent)无法正常工作的问题。本文将详细介绍如何正确开发Directus流程操作组件，并分析常见的配置错误。

核心问题分析

在Directus中创建自定义流程操作时，最常见的错误是扩展类型(type)配置不正确。Directus扩展系统要求明确区分不同类型的扩展，流程操作组件必须声明为"operation"类型，而不是"module"类型。

正确配置方法

1. package.json配置

正确的package.json配置应该包含以下关键部分：

"directus:extension": {
  "type": "operation",
  "path": {
    "app": "dist/app.js",
    "api": "dist/api.js"
  },
  "source": {
    "app": "src/app.ts",
    "api": "src/api.ts"
  },
  "host": "^10.10.0"
}

2. 项目结构

推荐的项目目录结构如下：

directus-extension-flow-hello/
├── package.json
├── src/
│   ├── app.ts       # 前端逻辑
│   ├── api.ts       # 后端逻辑
│   └── operations/
│       └── hello-world/
│           ├── index.ts
│           └── options.vue
└── dist/

实现细节

前端实现(app.ts)

前端部分需要定义操作的外观和行为：

import { defineOperationApp } from '@directus/extensions-sdk';
import HelloWorld from './operations/hello-world';

export default defineOperationApp({
  id: 'hello-world',
  name: 'Hello World',
  icon: 'hand_wave',
  description: 'A simple Hello World operation',
  overview: ({ name }) => [
    {
      label: 'Operation',
      text: name,
    },
  ],
  options: HelloWorld.options,
});

后端实现(api.ts)

后端部分处理操作的实际逻辑：

import { defineOperationComponent } from '@directus/extensions-sdk';
import Options from './operations/hello-world/options.vue';

export default defineOperationComponent({
  id: 'hello-world',
  name: 'Hello World',
  icon: 'hand_wave',
  description: 'Says hello to the world',
  component: Options,
  handler: async ({ text }, context) => {
    console.log(`Hello World: ${text}`);
    return `Operation completed: ${text}`;
  },
});

选项组件(options.vue)

Vue组件用于定义操作的配置界面：

<template>
  <div class="operation-options">
    <v-input
      v-model="text"
      :placeholder="t('enter_text')"
      :label="t('text_to_display')"
      class="full-width"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent, computed } from 'vue';
import { useI18n } from 'vue-i18n';

export default defineComponent({
  props: {
    modelValue: {
      type: Object,
      default: () => ({}),
    },
  },
  emits: ['update:modelValue'],
  setup(props, { emit }) {
    const { t } = useI18n();

    const text = computed({
      get: () => props.modelValue.text,
      set: (text) => emit('update:modelValue', { ...props.modelValue, text }),
    });

    return { t, text };
  },
});
</script>

常见问题解决

1. 组件不显示在流程编辑器中：检查package.json中的type是否为"operation"
2. 操作不执行：确保api.ts中的handler函数正确定义
3. 配置界面不显示：验证options.vue组件是否正确导入和导出

最佳实践

1. 使用TypeScript提高代码质量
2. 实现国际化支持(i18n)
3. 为操作组件添加清晰的描述和图标
4. 保持前端和后端逻辑分离
5. 为复杂操作添加详细的文档说明

总结

开发Directus自定义流程操作组件需要注意类型声明和项目结构的正确配置。通过遵循本文提供的指南，开发者可以避免常见的配置错误，创建出功能完善的自定义操作组件。记住始终验证扩展类型是否为"operation"，并确保前后端代码的正确分离和实现。