component

README

component — CMS 字段组件注册

提供 CMS 内容字段组件的注册与管理机制，每种字段类型（文本、富文本、关系、媒体等）对应一个 Component 实现。

核心接口

type Component interface {
    // Name 组件唯一标识（如 "text", "richtext", "relation"）
    Name() string

    // Validate 校验字段值是否符合组件规则
    Validate(ctx context.Context, config map[string]any, value any) error

    // GetOptions 获取下拉/单选组件的可选项列表
    GetOptions(ctx context.Context, config map[string]any) ([]Option, error)

    // PopulateDisplay 批量填充列表展示信息（用于关联字段）
    PopulateDisplay(ctx context.Context, config map[string]any, values []any) (map[any]Display, error)
}

注册组件

import "github.com/leeforge/framework/component"

// 注册自定义组件
err := component.Register(&MySelectComponent{})

// 重复注册同名组件会返回错误

获取组件

// 根据名称获取已注册的组件
comp, err := component.Get("select")
if err != nil {
    // 组件未注册
}

// 获取所有已注册组件
all := component.All()

实现自定义组件

type SelectComponent struct{}

func (c *SelectComponent) Name() string { return "select" }

func (c *SelectComponent) Validate(ctx context.Context, config map[string]any, value any) error {
    var cfg SelectConfig
    component.ParseConfig(config, &cfg)

    strVal, ok := value.(string)
    if !ok {
        return errors.New("select 字段值必须为字符串")
    }

    for _, opt := range cfg.Options {
        if opt.Value == strVal {
            return nil
        }
    }
    return fmt.Errorf("值 %q 不在可选项中", strVal)
}

func (c *SelectComponent) GetOptions(ctx context.Context, config map[string]any) ([]component.Option, error) {
    var cfg SelectConfig
    component.ParseConfig(config, &cfg)
    return cfg.Options, nil
}

func (c *SelectComponent) PopulateDisplay(ctx context.Context, config map[string]any, values []any) (map[any]component.Display, error) {
    options, _ := c.GetOptions(ctx, config)
    result := make(map[any]component.Display)
    for _, opt := range options {
        result[opt.Value] = component.Display{Label: opt.Label, Value: opt.Value}
    }
    return result, nil
}

工具函数

// ParseConfig 将 map[string]any 反序列化为结构体
type SelectConfig struct {
    Options []component.Option `json:"options"`
    Multiple bool              `json:"multiple"`
}
var cfg SelectConfig
component.ParseConfig(configMap, &cfg)

注意事项

• 组件注册应在应用启动时（plugin.Setup）调用，避免并发注册冲突
• PopulateDisplay 用于列表页批量填充，应尽量使用批量查询而非循环单查

Documentation

Index

• func Clear()
• func FilterFields(extra any, fields []string) any
• func List() []string
• func ParseConfig(config map[string]any, target any) error
• func ParseExtendJSON(extend string) map[string]any
• func Register(component Component) error
• func ShouldPopulateDisplay(config map[string]any) bool
• type Component
  • func Get(name string) (Component, error)
  • func MustGet(name string) Component
• type ComponentRegistry
• type Display
• type DisplayConfig
  • func ExtractDisplayConfig(config map[string]any) *DisplayConfig
• type Option
• type ValidationError
  • func NewValidationError(component, field, message string, err error) *ValidationError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Unwrap() error

Functions

func Clear

func Clear()

Clear 清空注册表（仅用于测试）

func FilterFields

func FilterFields(extra any, fields []string) any

FilterFields 根据 display.fields 过滤字段

func List

func List() []string

List 列出所有已注册组件

func ParseConfig

func ParseConfig(config map[string]any, target any) error

ParseConfig 解析组件配置

func ParseExtendJSON

func ParseExtendJSON(extend string) map[string]any

ParseExtendJSON 解析扩展字段（JSON 字符串）

func Register

func Register(component Component) error

Register 注册组件

func ShouldPopulateDisplay

func ShouldPopulateDisplay(config map[string]any) bool

ShouldPopulateDisplay 判断是否应该填充显示信息

Types

type Component

type Component interface {
	// Name 返回组件的唯一标识符
	Name() string

	// Validate 验证字段值是否符合组件规则
	Validate(ctx context.Context, config map[string]any, value any) error

	// GetOptions 获取字段的可选值列表（用于下拉框、单选框等）
	GetOptions(ctx context.Context, config map[string]any) ([]Option, error)

	// PopulateDisplay 批量填充字段的显示信息（用于列表展示）
	PopulateDisplay(ctx context.Context, config map[string]any, values []any) (map[any]Display, error)
}

Component 是所有组件必须实现的接口

func Get

func Get(name string) (Component, error)

Get 获取组件

func MustGet

func MustGet(name string) Component

MustGet 获取组件（panic if not found）

type ComponentRegistry

type ComponentRegistry struct {
	// contains filtered or unexported fields
}

ComponentRegistry 组件注册中心

type Display

type Display struct {
	Label string `json:"label"`           // 显示文本
	Value any    `json:"value"`           // 原始值
	Extra any    `json:"extra,omitempty"` // 扩展信息
}

Display 表示组件的显示信息

type DisplayConfig

type DisplayConfig struct {
	Mode   string   `json:"mode"`             // auto | always | never | on-demand
	Fields []string `json:"fields,omitempty"` // 需要填充的字段
	Cache  bool     `json:"cache,omitempty"`  // 是否缓存
}

DisplayConfig Display 配置

func ExtractDisplayConfig

func ExtractDisplayConfig(config map[string]any) *DisplayConfig

ExtractDisplayConfig 提取 Display 配置

type Option

type Option struct {
	Label string `json:"label"`           // 显示文本
	Value any    `json:"value"`           // 实际值
	Extra any    `json:"extra,omitempty"` // 额外信息（如颜色、图标）
}

Option 表示组件的可选项

type ValidationError

type ValidationError struct {
	Component string
	Field     string
	Message   string
	Err       error
}

ValidationError 组件验证错误

func NewValidationError

func NewValidationError(component, field, message string, err error) *ValidationError

NewValidationError 创建验证错误

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error