2026/9/9 20:45:22
FEATURED · 精选文章 
Directus Interfaces 接口开发指南深入解析 defineInterface 的字段编辑组件体系【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directusInterfaces接口组件是 Directus 管理后台中负责编辑与查看单条数据的原子化组件它们构成了表单中的一个个字段输入区。本指南以app/src/interfaces/readme.md的官方说明为骨架结合仓库内defineInterface的类型定义与input、boolean等真实实现带你在该开源仓库中理解 Directus 接口组件的结构、注册契约与选项声明方式最终掌握如何用 Vue 组件 配置元数据构建出可复用的自定义字段编辑控件。什么是 Directus InterfacesInterfaces 是 Directus 生态中与 Displays、Layouts、Modules 并列的四大 App 扩展点之一其定位可以用一句话概括接口组件是允许你编辑和查看某一条数据的独立输入块。在界面上的直观表现是表单中的每个字段都是一次 Interfaces 的渲染正如官方文档所说Interfaces can be seen as the individual fields in a form, where the field is a single column in a table.即表单中的字段 ↔ 表中的列而接口组件就是承载这一列的编辑 UI。整个接口目录位于仓库的 app/src/interfaces其中包含了input文本/数字输入、boolean开关、select-dropdown、list-m2m、file-image、map等约 40 个面向用户的接口组件以及一组以_system前缀命名的系统内部接口如_system/system-field、_system/system-permissions等后者用于 Directus 自身的系统字段配置界面。定义接口的起点defineInterface任何接口都必须通过defineInterface函数来声明注册借助它接口可以将自己的名称、图标、输入组件和可选参数统一挂载到 Directus 的字段配置体系中。官方文档给出了这样一个示例骨架export default defineInterface({ id: input, register: ({ i18n }) ({ name: i18n.global.t(input), icon: box, component: InterfaceTextInput, }), });需要特别说明的是上述register回调式写法来自官方旧版说明。从当前仓库的实际源码看接口配置已经演进为直接在配置对象顶层声明name、icon、component、types、group、options等属性的扁平形态见下文各节对照。无论形式如何变化其注册机制的本质没有变——defineInterface本身是一个类型辅助的身份函数identity function它的实现位于 packages/extensions/src/shared/utils/define-extension.ts#L18-L22接收配置对象后原样返回并补全类型约束export function defineInterfaceCustom extends CustomConfigInterfaceConfig( config: ExtendedConfigInterfaceConfig, Custom, ): ExtendedConfigInterfaceConfig, Custom { return config; }对应的单测 packages/extensions/src/shared/utils/define-extension.test.ts 也验证了这一点expect(defineInterface(interfaceConfig)).toBe(interfaceConfig)。它的作用是让编辑器在编写配置时获得完整的字段类型提示与校验并在需要时允许附带自定义扩展属性。接口的完整配置契约定义在 packages/types/src/extensions/interfaces.ts 的InterfaceConfig接口中。接口元数据字段逐一解析idid是接口在平台内的唯一标识。它不会直接展示给最终用户而是被内部用来构建表单与布局——例如某接口的options配置在描述自身设置项时会通过interface: select-icon、interface: select-color这类字符串反向引用其它接口作为设置项控件这些字符串对应的正是被引用接口的id。官方文档同时以id: input作为示例在源码中input接口的实际配置位于 app/src/interfaces/input/index.tsboolean接口则使用id: boolean见 app/src/interfaces/boolean/index.ts。在编写自定义接口时请务必保证id在平台内全局唯一避免与内置或第三方接口冲突。register与 context含 i18n在官方文档描述的旧式 API 中register是一个回调函数用于注册接口的选项与其他面向用户的参数。回调唯一接收的参数是context其承载内容如下属性说明i18nDirectus 内部集成的 vue-i18n 实例可用于返回翻译后的接口名称或翻译后的接口选项文本而如前所述当前仓库中的InterfaceConfig已将所有元数据收敛为顶层属性name、icon、component、options均直接声明不再经由register包裹。现代配置中的名称与描述常使用$t:key字符串键如$t:interfaces.input.input、$t:interfaces.input.description由 Directus 前端的国际化机制统一解析实际文案存储在 app/src/lang 下的各语言 YAML 文件中——这与文档中借助 i18n 实现本地化的目标一脉相承只是落地形式从函数调用变成了声明式键。namename是接口面向用户的展示名称。它在字段配置向导、接口下拉选择列表中直接呈现给管理员。如 app/src/interfaces/boolean/index.ts 中name: $t:interfaces.boolean.toggle会在界面上显示为各语言环境对应的Toggle/开关文本。文档强调借助i18n能力名称可以做到本地化——在扁平配置下即为使用翻译键而非硬编码字符串。iconicon是界面中提及该接口时展示的图标其最重要的出现场景是字段设置向导field-setup wizard中让用户挑选字段控件类型时的图标列表。图标使用 Directus 内置的 Material Design 图标名称字符串例如文本输入框接口用text_fields布尔开关接口用check_box。选择语义清晰的图标能显著提升数据建模时的辨识度。componentcomponent是构成接口输入的Vue 组件它会在编辑表单中被实际渲染。以 app/src/interfaces/input/input.vue 为例该组件通过script setup声明 props 接收字段的值与各类配置参数并依赖 Directus 通用输入组件VInput与图标组件VIcon位于 app/src/components搭建 UI。接口组件与 Directus 前端之间的数据契约遵循统一的约定通过valueprop 接收当前字段值通过input事件把新值回传给上层见源码中的defineEmits([input])。options面向字段配置的可视化参数面板接口的options描述的是该接口自身可配置的设置项字段管理员在字段的高级配置面板中修改这些选项时会实时以表单套表单的方式渲染出对应的编辑控件。依据 packages/types/src/extensions/interfaces.ts 的类型定义options支持四种形态一组DeepPartialAppField[]配置数组{ standard: AppField[]; advanced: AppField[] }分组对象标准/高级两栏展示一个接收ctx的函数根据上下文动态返回上述两种结构null或独立的 VueComponentOptions用于完全自定义的设置面板。input接口是按字段类型动态返回选项的典型范例app/src/interfaces/input/index.ts 中的options是一个函数它读取字段上下文{ field }若当前字段类型命中APP_NUMERIC_TYPES来自 app/src/constants.ts则返回min/max/step等数字专属选项默认step: 1否则返回placeholder、iconLeft、iconRight标准分组以及softLength软长度限制用于文字输入场景默认占位 255、fontsans-serif/monospace/serif 三选一默认sans-serif、trim、masked、clear、slug布尔开关默认均为false等文本选项。每个选项本身又是一个完整的DeepPartialField结构——拥有field选项键名、name、type、meta与schema.default_value其中meta.interface指定渲染该选项时复用的接口id如input、select-icon、select-dropdown、boolean、select-color。再看 app/src/interfaces/boolean/index.ts它展示了一套选项与组件 props 的一一映射iconOn/iconOff开启/关闭图标默认check_box与check_box_outline_blank、colorOn/colorOff高亮色、label展示文案且推荐了配套展示组件recommendedDisplays: [boolean]。也就是说声明 options 时给出的每个field键都会在运行期作为 prop 传入你的component。组件内部只需声明同名 props 即可消费这些配置例如 app/src/interfaces/input/input.vue 中定义了masked、trim、font、softLength、min、max、step等 props并在computed中据此计算输入框的typemasked时为password数字类型时为number与剩余字符数提示。这套配置即 props的约定让接口开发者无需关心选项面板如何构建只需专注在拿到这些参数后如何渲染输入这一件事上。分组、类型匹配与可选进阶字段除了文档重点讲解的id、register/name/icon/componentInterfaceConfig还定义了若干在当前仓库代码中大量使用的字段理解它们能帮你写出与既有生态风格一致的接口属性取值/类型作用说明description字符串/翻译键接口的补充说明展示于选择界面typesType[]如string、boolean、integer…声明该接口可用于哪些字段类型决定它在字段设置向导中的可选项范围必填localTypesLocalType[]面向 alias、m2m、o2m 等本地非原生 DB类型的适用声明groupstandard|selection|relational|presentation|group|other接口所属分组决定在向导中的归类展示ordernumber在同一分组内的排序权重relationalboolean标记为关系型接口如 m2m/o2m 列表影响加载与权限处理recommendedDisplaysstring[]为使用该接口的字段推荐默认的展示Display组件 idpreviewstring如PreviewSVG可选的缩略预览图/组件用于在设置向导中直观呈现输入效果systemboolean是否为系统内部接口_system目录下的接口均为true风格实现以input为例其声明为types: [string, uuid, bigInteger, integer, float, decimal, text]、group: standard因此当你新建一个文本或整数字段时向导才会把Input列为候选控件boolean则声明types: [boolean]、group: selection只服务于布尔类型字段。这种类型白名单机制让字段建模界面保持克制且语义明确。把接口放进 App 扩展生态defineInterface与defineDisplay、defineLayout、defineModule、definePanel等函数一起被统一导出自directus/extensions它们构成 Directus 前端扩展声明的统一入口实现文件均为 packages/extensions/src/shared/utils/define-extension.ts 中的同构身份函数。一条接口从声明到出现在编辑表单中的完整链路可概括为声明配置调用defineInterface传入InterfaceConfigid/name/icon/component/types/group/options…类型注册配置对象经类型校验后原样返回由扩展注册器收集进平台的接口注册表场景消费字段设置向导按typesgroup过滤出可用接口列表并展示icon与name管理员保存字段后编辑表单即渲染该接口的component并将字段值与已配置的options作为 props 传入交互回写组件通过input事件把编辑结果回传完成一次数据编辑。小结本文以官方文档为纲拆解了 Directus 接口组件的定义方式与四个核心元数据——用于内部定位的id、承载用户可见信息的register含i18n本地化能力、用于向导展示的name/icon以及真正渲染输入的component并结合当前仓库源码补齐了options动态声明、types/group匹配、recommendedDisplays与 props 数据契约等进阶细节。若你正打算为 Directus 编写第一个自定义接口可先阅读 packages/types/src/extensions/interfaces.ts 掌握全部可配置字段再对照 app/src/interfaces/input/index.ts 与 app/src/interfaces/boolean/index.ts 两份最小而完整的范例动手实践即可快速产出符合平台规范、可本地化、可随字段类型自适应的输入控件。【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Directus Interfaces 接口开发指南：深入解析 defineInterface 的字段编辑组件体系
Directus Interfaces 接口开发指南深入解析 defineInterface 的字段编辑组件体系【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directusInterfaces接口组件是 Directus 管理后台中负责编辑与查看单条数据的原子化组件它们构成了表单中的一个个字段输入区。本指南以app/src/interfaces/readme.md的官方说明为骨架结合仓库内defineInterface的类型定义与input、boolean等真实实现带你在该开源仓库中理解 Directus 接口组件的结构、注册契约与选项声明方式最终掌握如何用 Vue 组件 配置元数据构建出可复用的自定义字段编辑控件。什么是 Directus InterfacesInterfaces 是 Directus 生态中与 Displays、Layouts、Modules 并列的四大 App 扩展点之一其定位可以用一句话概括接口组件是允许你编辑和查看某一条数据的独立输入块。在界面上的直观表现是表单中的每个字段都是一次 Interfaces 的渲染正如官方文档所说Interfaces can be seen as the individual fields in a form, where the field is a single column in a table.即表单中的字段 ↔ 表中的列而接口组件就是承载这一列的编辑 UI。整个接口目录位于仓库的 app/src/interfaces其中包含了input文本/数字输入、boolean开关、select-dropdown、list-m2m、file-image、map等约 40 个面向用户的接口组件以及一组以_system前缀命名的系统内部接口如_system/system-field、_system/system-permissions等后者用于 Directus 自身的系统字段配置界面。定义接口的起点defineInterface任何接口都必须通过defineInterface函数来声明注册借助它接口可以将自己的名称、图标、输入组件和可选参数统一挂载到 Directus 的字段配置体系中。官方文档给出了这样一个示例骨架export default defineInterface({ id: input, register: ({ i18n }) ({ name: i18n.global.t(input), icon: box, component: InterfaceTextInput, }), });需要特别说明的是上述register回调式写法来自官方旧版说明。从当前仓库的实际源码看接口配置已经演进为直接在配置对象顶层声明name、icon、component、types、group、options等属性的扁平形态见下文各节对照。无论形式如何变化其注册机制的本质没有变——defineInterface本身是一个类型辅助的身份函数identity function它的实现位于 packages/extensions/src/shared/utils/define-extension.ts#L18-L22接收配置对象后原样返回并补全类型约束export function defineInterfaceCustom extends CustomConfigInterfaceConfig( config: ExtendedConfigInterfaceConfig, Custom, ): ExtendedConfigInterfaceConfig, Custom { return config; }对应的单测 packages/extensions/src/shared/utils/define-extension.test.ts 也验证了这一点expect(defineInterface(interfaceConfig)).toBe(interfaceConfig)。它的作用是让编辑器在编写配置时获得完整的字段类型提示与校验并在需要时允许附带自定义扩展属性。接口的完整配置契约定义在 packages/types/src/extensions/interfaces.ts 的InterfaceConfig接口中。接口元数据字段逐一解析idid是接口在平台内的唯一标识。它不会直接展示给最终用户而是被内部用来构建表单与布局——例如某接口的options配置在描述自身设置项时会通过interface: select-icon、interface: select-color这类字符串反向引用其它接口作为设置项控件这些字符串对应的正是被引用接口的id。官方文档同时以id: input作为示例在源码中input接口的实际配置位于 app/src/interfaces/input/index.tsboolean接口则使用id: boolean见 app/src/interfaces/boolean/index.ts。在编写自定义接口时请务必保证id在平台内全局唯一避免与内置或第三方接口冲突。register与 context含 i18n在官方文档描述的旧式 API 中register是一个回调函数用于注册接口的选项与其他面向用户的参数。回调唯一接收的参数是context其承载内容如下属性说明i18nDirectus 内部集成的 vue-i18n 实例可用于返回翻译后的接口名称或翻译后的接口选项文本而如前所述当前仓库中的InterfaceConfig已将所有元数据收敛为顶层属性name、icon、component、options均直接声明不再经由register包裹。现代配置中的名称与描述常使用$t:key字符串键如$t:interfaces.input.input、$t:interfaces.input.description由 Directus 前端的国际化机制统一解析实际文案存储在 app/src/lang 下的各语言 YAML 文件中——这与文档中借助 i18n 实现本地化的目标一脉相承只是落地形式从函数调用变成了声明式键。namename是接口面向用户的展示名称。它在字段配置向导、接口下拉选择列表中直接呈现给管理员。如 app/src/interfaces/boolean/index.ts 中name: $t:interfaces.boolean.toggle会在界面上显示为各语言环境对应的Toggle/开关文本。文档强调借助i18n能力名称可以做到本地化——在扁平配置下即为使用翻译键而非硬编码字符串。iconicon是界面中提及该接口时展示的图标其最重要的出现场景是字段设置向导field-setup wizard中让用户挑选字段控件类型时的图标列表。图标使用 Directus 内置的 Material Design 图标名称字符串例如文本输入框接口用text_fields布尔开关接口用check_box。选择语义清晰的图标能显著提升数据建模时的辨识度。componentcomponent是构成接口输入的Vue 组件它会在编辑表单中被实际渲染。以 app/src/interfaces/input/input.vue 为例该组件通过script setup声明 props 接收字段的值与各类配置参数并依赖 Directus 通用输入组件VInput与图标组件VIcon位于 app/src/components搭建 UI。接口组件与 Directus 前端之间的数据契约遵循统一的约定通过valueprop 接收当前字段值通过input事件把新值回传给上层见源码中的defineEmits([input])。options面向字段配置的可视化参数面板接口的options描述的是该接口自身可配置的设置项字段管理员在字段的高级配置面板中修改这些选项时会实时以表单套表单的方式渲染出对应的编辑控件。依据 packages/types/src/extensions/interfaces.ts 的类型定义options支持四种形态一组DeepPartialAppField[]配置数组{ standard: AppField[]; advanced: AppField[] }分组对象标准/高级两栏展示一个接收ctx的函数根据上下文动态返回上述两种结构null或独立的 VueComponentOptions用于完全自定义的设置面板。input接口是按字段类型动态返回选项的典型范例app/src/interfaces/input/index.ts 中的options是一个函数它读取字段上下文{ field }若当前字段类型命中APP_NUMERIC_TYPES来自 app/src/constants.ts则返回min/max/step等数字专属选项默认step: 1否则返回placeholder、iconLeft、iconRight标准分组以及softLength软长度限制用于文字输入场景默认占位 255、fontsans-serif/monospace/serif 三选一默认sans-serif、trim、masked、clear、slug布尔开关默认均为false等文本选项。每个选项本身又是一个完整的DeepPartialField结构——拥有field选项键名、name、type、meta与schema.default_value其中meta.interface指定渲染该选项时复用的接口id如input、select-icon、select-dropdown、boolean、select-color。再看 app/src/interfaces/boolean/index.ts它展示了一套选项与组件 props 的一一映射iconOn/iconOff开启/关闭图标默认check_box与check_box_outline_blank、colorOn/colorOff高亮色、label展示文案且推荐了配套展示组件recommendedDisplays: [boolean]。也就是说声明 options 时给出的每个field键都会在运行期作为 prop 传入你的component。组件内部只需声明同名 props 即可消费这些配置例如 app/src/interfaces/input/input.vue 中定义了masked、trim、font、softLength、min、max、step等 props并在computed中据此计算输入框的typemasked时为password数字类型时为number与剩余字符数提示。这套配置即 props的约定让接口开发者无需关心选项面板如何构建只需专注在拿到这些参数后如何渲染输入这一件事上。分组、类型匹配与可选进阶字段除了文档重点讲解的id、register/name/icon/componentInterfaceConfig还定义了若干在当前仓库代码中大量使用的字段理解它们能帮你写出与既有生态风格一致的接口属性取值/类型作用说明description字符串/翻译键接口的补充说明展示于选择界面typesType[]如string、boolean、integer…声明该接口可用于哪些字段类型决定它在字段设置向导中的可选项范围必填localTypesLocalType[]面向 alias、m2m、o2m 等本地非原生 DB类型的适用声明groupstandard|selection|relational|presentation|group|other接口所属分组决定在向导中的归类展示ordernumber在同一分组内的排序权重relationalboolean标记为关系型接口如 m2m/o2m 列表影响加载与权限处理recommendedDisplaysstring[]为使用该接口的字段推荐默认的展示Display组件 idpreviewstring如PreviewSVG可选的缩略预览图/组件用于在设置向导中直观呈现输入效果systemboolean是否为系统内部接口_system目录下的接口均为true风格实现以input为例其声明为types: [string, uuid, bigInteger, integer, float, decimal, text]、group: standard因此当你新建一个文本或整数字段时向导才会把Input列为候选控件boolean则声明types: [boolean]、group: selection只服务于布尔类型字段。这种类型白名单机制让字段建模界面保持克制且语义明确。把接口放进 App 扩展生态defineInterface与defineDisplay、defineLayout、defineModule、definePanel等函数一起被统一导出自directus/extensions它们构成 Directus 前端扩展声明的统一入口实现文件均为 packages/extensions/src/shared/utils/define-extension.ts 中的同构身份函数。一条接口从声明到出现在编辑表单中的完整链路可概括为声明配置调用defineInterface传入InterfaceConfigid/name/icon/component/types/group/options…类型注册配置对象经类型校验后原样返回由扩展注册器收集进平台的接口注册表场景消费字段设置向导按typesgroup过滤出可用接口列表并展示icon与name管理员保存字段后编辑表单即渲染该接口的component并将字段值与已配置的options作为 props 传入交互回写组件通过input事件把编辑结果回传完成一次数据编辑。小结本文以官方文档为纲拆解了 Directus 接口组件的定义方式与四个核心元数据——用于内部定位的id、承载用户可见信息的register含i18n本地化能力、用于向导展示的name/icon以及真正渲染输入的component并结合当前仓库源码补齐了options动态声明、types/group匹配、recommendedDisplays与 props 数据契约等进阶细节。若你正打算为 Directus 编写第一个自定义接口可先阅读 packages/types/src/extensions/interfaces.ts 掌握全部可配置字段再对照 app/src/interfaces/input/index.ts 与 app/src/interfaces/boolean/index.ts 两份最小而完整的范例动手实践即可快速产出符合平台规范、可本地化、可随字段类型自适应的输入控件。【免费下载链接】directusThe flexible backend for all your projects Turn your DB into a headless CMS, admin panels, or apps with a custom UI, instant APIs, auth more.项目地址: https://gitcode.com/GitHub_Trending/di/directus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
