LynxHTMLRenderer 插件系统#

export type TransformPhase =
  | "normalize" // AST 预处理：实体解码、空白归一化
  | "structure" // HTML 结构语义：标签转换、树构建
  | "capability" // LynxNode 能力建模：样式、布局、媒体
  | "finalize"; // 收尾处理：预留扩展

export interface TransformPlugin {
  /** 插件唯一标识（用于禁用 / 替换） */
  name: string;
  /** 所属执行阶段 */
  phase: TransformPhase;
  /** 同 phase 内执行顺序（数字越小越先执行） */
  order?: number;
  /** 是否默认启用 */
  enabledByDefault?: boolean;

  /** 可选：注册能力处理器（推荐用于 capability 阶段）
   *
   * 返回一个 Map，key 是节点类型（tag），value 是对应的处理器
   * 引擎会在一次遍历中调用所有相关的处理器，提高性能
   *
   * 如果此方法存在，将优先于 apply() 使用
   */
  registerCapabilityHandlers?: (
    ctx: TransformContext,
  ) => Map<string, NodeCapabilityHandler>;

  /** 插件执行入口（传统方式，向后兼容） */
  apply(ctx: TransformContext): void;
}

/** 节点能力处理器类型 */
type NodeCapabilityHandler = (
  node: LynxNode,
  ctx: TransformContext,
) => void | LynxNode;

export interface TransformContext {
  /** 只读：HTML AST 根节点 */
  readonly ast: HtmlAstNode;
  /** 可写：LynxNode 根节点 */
  root: LynxNode;
  /** 工具方法 */
  utils: {
    /** 遍历 AST 所有节点 */
    walkAst(cb: (node: HtmlAstNode) => void): void;
    /** 创建新的 LynxNode */
    createNode(partial: Partial<LynxNode>): LynxNode;
    /** 替换已有 LynxNode */
    replaceNode(target: LynxNode, next: LynxNode): void;
    /** 注册能力处理器（用于批量处理优化） */
    registerHandler(nodeKind: string, handler: NodeCapabilityHandler): void;
  };
  /** 元数据：插件间传递非结构化信息 */
  metadata: Record<string, unknown>;
  /** 内部：处理器注册表（用于批量处理） */
  _handlerRegistry?: Map<string, NodeCapabilityHandler[]>;
}

export interface PluginConfig {
  /** 禁用指定的内建插件 */
  disable?: string[];
  /** 替换指定的内建插件 */
  replace?: Record<string, TransformPlugin>;
  /** 添加额外的自定义插件 */
  extra?: TransformPlugin[];
}

const phaseOrder: Record<TransformPhase, number> = {
  normalize: 1,
  structure: 2,
  capability: 3,
  finalize: 4,
};

// 先按 phase 分组，同 phase 内按 order 排序
plugins.sort((a, b) => {
  const phaseDiff = phaseOrder[a.phase] - phaseOrder[b.phase];
  if (phaseDiff !== 0) return phaseDiff;
  return (a.order ?? 0) - (b.order ?? 0);
});

for (const phase of ["normalize", "structure", "capability", "finalize"]) {
  const plugins = resolver.getPluginsByPhase(phase);
  for (const plugin of plugins) {
    plugin.apply(ctx);
  }
}

import type { TransformPlugin } from "lynx-html-renderer/transform";

const myCapabilityPlugin: TransformPlugin = {
  name: "my-capability",
  phase: "capability",
  order: 50,

  // 注册处理器（推荐用于 capability 阶段）
  registerCapabilityHandlers(ctx) {
    const handlers = new Map<string, NodeCapabilityHandler>();

    // 为 "view" 节点注册处理器
    handlers.set('view', (node) => {
      // ❌ BAD: 直接处理，没有提前检查
      // node.props = { ...node.props, customAttr: processComplex(node) };

      // ✅ GOOD: 提前检查 + 快速返回
      if (!node.meta?.sourceAttrs?.['data-custom']) return;  // 快速跳过不相关节点
      if (ctx.metadata.skipCustomAttrs) return;                // 全局配置检查

      // 只有通过所有检查才执行实际处理
      node.props = {
        ...node.props,
        customAttr: node.meta.sourceAttrs['data-custom'],
      };
    });

    // 一个插件可以处理多种节点类型
    handlers.set('text', (node) => {
      if (!node.meta?.sourceAttrs?.['data-text-custom']) return;
      // 处理 text 节点的特殊逻辑
    });

    handlers.set('image', (node) => {
      if (!node.meta?.sourceAttrs?.['data-image-custom']) return;
      // 处理 image 节点的特殊逻辑
    });

    return handlers;
  },

  // 传统 apply() 方法（向后兼容）
  apply(ctx) {
    // 如果 registerCapabilityHandlers 存在，此方法将被忽略
    ctx.utils.walkAst((node) => {
      // ... 传统实现 ...
    });
  },
};

import { transformHTML } from "lynx-html-renderer/html-parser";

const html = "<div>Hello World</div>";
const nodes = transformHTML(html);

const nodes = transformHTML(html, {
  plugins: {
    disable: ["table-structure"],
  },
});

const customPlugin: TransformPlugin = {
  name: "block-structure",
  phase: "structure",
  order: 10,
  apply(ctx) {
    // 自定义逻辑
  },
};

const nodes = transformHTML(html, {
  plugins: {
    replace: {
      "block-structure": customPlugin,
    },
  },
});

const analyticsPlugin: TransformPlugin = {
  name: "analytics",
  phase: "capability",
  order: 1000,
  apply(ctx) {
    ctx.utils.walkAst((node) => {
      ctx.metadata.nodeCount = ((ctx.metadata.nodeCount as number) ?? 0) + 1;
    });
  },
};

const nodes = transformHTML(html, {
  plugins: {
    extra: [analyticsPlugin],
  },
});

const nodes = transformHTML(html, {
  removeAllClass: true,
  removeAllStyle: false,
  plugins: {
    disable: ["text-merge"],
    replace: {
      "media-capability": myCustomMediaPlugin,
    },
    extra: [analyticsPlugin, customTagPlugin],
  },
});

import type { TransformPlugin } from "lynx-html-renderer/transform";

const myPlugin: TransformPlugin = {
  name: "my-custom-plugin",
  phase: "capability",
  order: 50,
  enabledByDefault: true,
  apply(ctx) {
    // 访问 AST
    ctx.utils.walkAst((node) => {
      // 处理 AST 节点
    });

    // 访问 LynxNode Tree
    const root = ctx.root;

    // 创建/替换节点
    const newNode = ctx.utils.createNode({ kind: "text", content: "Hello" });
    ctx.utils.replaceNode(oldNode, newNode);

    // 使用 metadata 与其他插件通信
    ctx.metadata.myData = "value";
  },
};