插件开发

interface RenderPlugin {
  /** 插件名称，用于日志和错误提示 */
  name: string
  /** 执行顺序：pre（前置）→ normal（普通）→ post（后置），默认 normal */
  enforce?: 'pre' | 'normal' | 'post'
  /** 过滤器：返回 false 时跳过当前模板，不执行钩子 */
  apply?: (path: string) => boolean
  /** 渲染前钩子：在 React SSR 之前执行 */
  beforeRender?: (ctx: PluginContext) => void | Promise<void>
  /** 渲染后钩子：在模板片段生成后、HtmlWrapper 包装前执行，拿到的是组件片段而非完整文档，可以加工片段 HTML */
  afterRender?: (ctx: PluginContext & { html: string }) => string | void | Promise<string | void>
}

import type { RenderPlugin } from '@karinjs/template-react'

const prePlugin: RenderPlugin = {
  name: 'pre-plugin',
  enforce: 'pre', // 最先执行
  beforeRender: () => console.log('1. pre beforeRender')
}

const normalPlugin: RenderPlugin = {
  name: 'normal-plugin',
  // enforce: 'normal' 是默认值，可省略
  beforeRender: () => console.log('2. normal beforeRender')
}

const postPlugin: RenderPlugin = {
  name: 'post-plugin',
  enforce: 'post', // 最后执行
  beforeRender: () => console.log('3. post beforeRender')
}

const userOnlyPlugin: RenderPlugin = {
  name: 'user-only',
  apply: (path) => path.startsWith('user/'), // 只对 user/* 生效
  beforeRender: (ctx) => {
    console.log(`[user-only] 渲染 ${ctx.path}`)
  }
}

const excludeDraftPlugin: RenderPlugin = {
  name: 'exclude-draft',
  apply: (path) => !path.includes('draft'), // 排除 draft 模板
  afterRender: (ctx) => {
    // afterRender 拿到的是组件片段（没有 </body>），直接追加节点即可
    return ctx.html + '<div class="watermark">正式版</div>'
  }
}

const conditionalPlugin: RenderPlugin = {
  name: 'conditional',
  apply: (path) => {
    // 正则匹配
    if (/^(user|admin)\//.test(path)) return true

    // 环境变量控制
    if (process.env.NODE_ENV === 'development' && path.includes('test')) return true

    // 白名单
    const whitelist = ['hello/card', 'user/profile']
    return whitelist.includes(path)
  },
  beforeRender: () => {
    /* ... */
  }
}

interface PluginContext {
  /** 模板路由（如 'hello/card'） */
  path: string
  /** 当前渲染的数据 */
  data: unknown
  /** 运行时上下文（scale、theme） */
  ctx: RenderContext
  /** HTML 输出目录 */
  outputDir: string
}

const logPlugin: RenderPlugin = {
  name: 'log-plugin',
  beforeRender: async (ctx) => {
    console.log(`[渲染前] 路由: ${ctx.path}`)
    console.log(`[渲染前] 数据:`, ctx.data)
    console.log(`[渲染前] 主题:`, ctx.ctx.theme)
  }
}

const validatePlugin: RenderPlugin = {
  name: 'validate-data',
  beforeRender: (ctx) => {
    if (!ctx.data || typeof ctx.data !== 'object') {
      throw new Error(`[${ctx.path}] 数据无效：必须是对象`)
    }

    // 检查必填字段
    const data = ctx.data as Record<string, unknown>
    if (!data.title) {
      console.warn(`[${ctx.path}] 缺少 title 字段`)
    }
  }
}

import type { RenderPlugin } from '@karinjs/template-react'

const perfMap = new Map<string, number>()

const perfPlugin: RenderPlugin = {
  name: 'perf-monitor',
  beforeRender: (ctx) => {
    perfMap.set(ctx.path, Date.now())
  },
  afterRender: (ctx) => {
    const start = perfMap.get(ctx.path)
    if (start) {
      const duration = Date.now() - start
      console.log(`[性能] ${ctx.path} 渲染耗时: ${duration}ms`)
      perfMap.delete(ctx.path)
    }
  }
}

const transformPlugin: RenderPlugin = {
  name: 'transform',
  afterRender: async (ctx) => {
    // 读取原 HTML
    const { html } = ctx

    // 加工
    let transformed = html.replace('{{VERSION}}', '1.0.0')

    // 返回新 HTML
    return transformed
  }
}

import type { RenderPlugin } from '@karinjs/template-react'
import { minify } from 'html-minifier-terser'

const minifyPlugin: RenderPlugin = {
  name: 'html-minify',
  enforce: 'post', // 最后执行
  afterRender: async (ctx) => {
    return await minify(ctx.html, {
      collapseWhitespace: true,
      removeComments: true,
      minifyCSS: true,
      minifyJS: true
    })
  }
}

export default defineConfig({
  html: {
    headExtra: `
      <meta name="generator" content="ktr">
      <meta name="template" content="user/card">
    `
  }
})

const watermarkPlugin: RenderPlugin = {
  name: 'watermark',
  apply: (path) => !path.includes('official'), // 非正式版才加水印
  afterRender: (ctx) => {
    const watermark = `
      <div style="position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%) rotate(-45deg); font-size: 72px; color: rgba(0,0,0,0.05); pointer-events: none; user-select: none; z-index: 9999;">
        DRAFT
      </div>
    `
    // 片段没有 </body>，直接追加节点（外壳 #container 是 position: relative 定位包含块）
    return ctx.html + watermark
  }
}

import type { RenderPlugin } from '@karinjs/template-react'
import fs from 'node:fs'
import path from 'node:path'

const inlineAssetsPlugin: RenderPlugin = {
  name: 'inline-assets',
  afterRender: async (ctx) => {
    // 注意时机：afterRender 在 HtmlWrapper 包装前执行，此时 /assets 引用还是模板原始写法
    // （框架的 base64/file:// 改写发生在之后的包装阶段），所以这里能匹配到原始路径
    let html = ctx.html

    // 内联小图片（< 10KB）
    const imgRegex = /<img[^>]+src="\/assets\/([^"]+)"[^>]*>/g
    html = html.replace(imgRegex, (match, filename) => {
      const filepath = path.join(ctx.outputDir, '../assets', filename)
      if (!fs.existsSync(filepath)) return match

      const stat = fs.statSync(filepath)
      if (stat.size > 10240) return match // 超过 10KB 不内联

      const ext = path.extname(filename).slice(1)
      const content = fs.readFileSync(filepath, 'base64')
      return match.replace(`src="/assets/${filename}"`, `src="data:image/${ext};base64,${content}"`)
    })

    return html
  }
}

import type { RenderPlugin } from '@karinjs/template-react'
import fs from 'node:fs'
import path from 'node:path'

const capturePlugin: RenderPlugin = {
  name: 'capture-data',
  enforce: 'post',
  beforeRender: async (ctx) => {
    const templateDir = path.join(ctx.outputDir, '../template', ctx.path)
    const dataDir = path.join(templateDir, 'data')
    const capturedFile = path.join(dataDir, 'captured.json')

    // 确保目录存在
    await fs.promises.mkdir(dataDir, { recursive: true })

    // 写入捕获数据
    await fs.promises.writeFile(capturedFile, JSON.stringify({ data: ctx.data, ctx: ctx.ctx }, null, 2))
  }
}

import type { RenderPlugin } from '@karinjs/template-react'

const errorReportPlugin: RenderPlugin = {
  name: 'error-report',
  beforeRender: async (ctx) => {
    try {
      // 数据校验
      if (!ctx.data) throw new Error('数据为空')
    } catch (error) {
      // 上报到监控平台
      await fetch('https://monitor.example.com/report', {
        method: 'POST',
        body: JSON.stringify({
          path: ctx.path,
          error: (error as Error).message,
          timestamp: Date.now()
        })
      })
      throw error // 重新抛出
    }
  }
}

import type { RenderPlugin } from '@karinjs/template-react'
import fs from 'node:fs'
import path from 'node:path'
import crypto from 'node:crypto'

const cachePlugin: RenderPlugin = {
  name: 'cache',
  enforce: 'pre',
  beforeRender: async (ctx) => {
    const cacheDir = path.join(ctx.outputDir, '.cache')
    await fs.promises.mkdir(cacheDir, { recursive: true })

    // 计算数据哈希
    const hash = crypto.createHash('md5').update(JSON.stringify(ctx.data)).digest('hex')

    const cacheFile = path.join(cacheDir, `${ctx.path.replace('/', '_')}_${hash}.html`)

    // 检查缓存
    if (fs.existsSync(cacheFile)) {
      console.log(`[缓存] 命中: ${ctx.path}`)
      // 跳过渲染（需要框架支持，此处仅示意）
    }
  }
}

export default defineConfig({
  html: {
    headExtra: `
      <meta property="og:title" content="模板预览">
      <meta property="og:type" content="website">
      <meta property="og:image" content="/preview/user_card.png">
    `
  }
})

import type { RenderPlugin } from '@karinjs/template-react'

const i18nPlugin: RenderPlugin = {
  name: 'i18n',
  afterRender: (ctx) => {
    const lang = (ctx.ctx as any).lang || 'zh-CN'
    // 片段里没有 <html> 标签，用一层带 lang 的包裹 div 代替
    return `<div lang="${lang}">${ctx.html}</div>`
  }
}

const responsiveImagePlugin: RenderPlugin = {
  name: 'responsive-image',
  afterRender: (ctx) => {
    // 将 <img> 转换为 <picture>
    return ctx.html.replace(
      /<img src="([^"]+)" alt="([^"]*)"/g,
      (match, src, alt) => `
        <picture>
          <source srcset="${src}?w=640" media="(max-width: 640px)">
          <source srcset="${src}?w=1280" media="(max-width: 1280px)">
          <img src="${src}" alt="${alt}"
        </picture>
      `
    )
  }
}

export default defineConfig({
  html: {
    headExtra: `
      <meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:">
    `
  }
})

import type { RenderPlugin } from '@karinjs/template-react'
import fs from 'node:fs'
import path from 'node:path'

const statsPlugin: RenderPlugin = {
  name: 'stats',
  enforce: 'post',
  afterRender: async (ctx) => {
    const statsFile = path.join(ctx.outputDir, 'stats.json')

    let stats: Record<string, any> = {}
    if (fs.existsSync(statsFile)) {
      stats = JSON.parse(fs.readFileSync(statsFile, 'utf-8'))
    }

    stats[ctx.path] = {
      htmlSize: ctx.html.length,
      renderTime: Date.now(),
      theme: ctx.ctx.theme?.mode || 'default'
    }

    await fs.promises.writeFile(statsFile, JSON.stringify(stats, null, 2))
  }
}

import { defineConfig } from '@karinjs/template-react'
import type { RenderPlugin } from '@karinjs/template-react'

const myPlugin: RenderPlugin = {
  name: 'my-plugin',
  beforeRender: () => {
    /* ... */
  }
}

export default defineConfig({
  // 通过 vite.plugins 无效，需要通过运行时注册
})

const render = createRenderer(templates, {
  cssPath,
  outputDir,
  plugins: [minifyPlugin]
})

import { createTemplateRenderer } from '@karinjs/template-react'
import type { RenderPlugin } from '@karinjs/template-react'

const watermarkPlugin: RenderPlugin = {
  name: 'watermark',
  // afterRender 拿到的是组件片段（没有 </body>），直接追加节点
  afterRender: (ctx) => ctx.html + '<div class="watermark">My Bot</div>'
}

const render = createTemplateRenderer(import.meta.url, {
  renderer: { plugins: [watermarkPlugin] }
})

export default render

const safePlugin: RenderPlugin = {
  name: 'safe',
  beforeRender: async (ctx) => {
    try {
      // 可能失败的操作
      await riskyOperation()
    } catch (error) {
      console.error(`[${ctx.path}] 插件失败:`, error)
      // 不重新抛出，避免中断渲染
    }
  }
}

const asyncPlugin: RenderPlugin = {
  name: 'async',
  afterRender: async (ctx) => {
    // ✅ 好：异步上传，不阻塞返回
    uploadToStorage(ctx.html).catch(console.error)
    return ctx.html // 立即返回
  }
}

import type { RenderPlugin } from '@karinjs/template-react'

function createWatermarkPlugin(text: string, opacity = 0.05): RenderPlugin {
  return {
    name: 'watermark',
    afterRender: (ctx) => {
      // 片段没有 </body>，直接追加节点
      const watermark = `<div style="opacity: ${opacity}">${text}</div>`
      return ctx.html + watermark
    }
  }
}

// 使用
const plugin = createWatermarkPlugin('DRAFT', 0.1)

// ✅ 好：声明式过滤
const plugin: RenderPlugin = {
  name: 'prod-only',
  apply: () => process.env.NODE_ENV === 'production',
  afterRender: minify
}

// ❌ 差：命令式判断
const badPlugin: RenderPlugin = {
  name: 'prod-only',
  afterRender: (ctx) => {
    if (process.env.NODE_ENV !== 'production') return
    return minify(ctx)
  }
}

declare function minify(ctx: any): any

import type { RenderPlugin, PluginContext } from '@karinjs/template-react'

interface UserCardData {
  name: string
  avatar: string
}

function isUserCardData(data: unknown): data is UserCardData {
  return typeof data === 'object' && data !== null && 'name' in data
}

const typedPlugin: RenderPlugin = {
  name: 'typed',
  apply: (path) => path === 'user/card',
  beforeRender: (ctx) => {
    if (!isUserCardData(ctx.data)) {
      throw new Error('数据类型错误')
    }
    // 此处 ctx.data 类型已缩窄
    console.log(ctx.data.name)
  }
}