移植 WordPress 插件

许多 WordPress 插件可以移植到 EmDash。插件模型有所不同——使用 TypeScript 而非 PHP，使用钩子而非动作/过滤器，使用结构化存储而非 wp_options——但大多数功能都能清晰地映射。

可移植性评估

并非所有插件都适合移植。在开始前请评估候选插件。

适合移植的插件

自定义字段、SEO 插件、内容处理器、管理界面扩展、分析工具、社交分享、表单

不适合移植的插件

多站点功能、WooCommerce/Gutenberg 集成、修补 WordPress 核心内部机制的插件

插件结构对比

WordPress

wp-content/plugins/my-plugin/
├── my-plugin.php       # Main file with plugin header
├── includes/
│   ├── class-admin.php
│   └── class-api.php
└── admin/
    └── js/

EmDash

my-plugin/
├── src/
│   ├── index.ts    # Plugin definition (definePlugin)
│   └── admin.tsx   # Admin UI exports (React)
├── package.json
└── tsconfig.json

钩子映射

WordPress 使用带有字符串钩子名称的 add_action() 和 add_filter()。EmDash 使用在插件定义中声明的类型化钩子。

生命周期钩子

WordPress	EmDash	说明
register_activation_hook()	plugin:install	首次安装时运行一次
插件启用	plugin:activate	启用时运行
插件禁用	plugin:deactivate	禁用时运行
register_uninstall_hook()	plugin:uninstall	event.deleteData 指示用户选择

内容钩子

WordPress	EmDash	说明
wp_insert_post_data	content:beforeSave	返回修改后的内容或抛出异常以取消
save_post	content:afterSave	保存后的副作用操作
before_delete_post	content:beforeDelete	返回 false 以取消删除
deleted_post	content:afterDelete	删除后的清理操作

WordPress

add_action('save_post', function($post_id, $post, $update) {
    if ($post->post_type !== 'product') return;

    $price = get_post_meta($post_id, 'price', true);
    if ($price > 1000) {
        update_post_meta($post_id, 'is_premium', true);
    }

}, 10, 3);

EmDash

hooks: {
    "content:afterSave": async (event, ctx) => {
        if (event.collection !== "products") return;

        const price = event.content.price as number;
        if (price > 1000) {
            await ctx.kv.set(`premium:${event.content.id}`, true);
        }
    },
}

媒体钩子

WordPress	EmDash	说明
wp_handle_upload_prefilter	media:beforeUpload	验证或转换
add_attachment	media:afterUpload	上传后响应

存储映射

选项 API → 键值存储

WordPress

$api_key = get_option('my_plugin_api_key', '');
update_option('my_plugin_api_key', 'abc123');
delete_option('my_plugin_api_key');

EmDash

const apiKey = await ctx.kv.get<string>("settings:apiKey") ?? "";
await ctx.kv.set("settings:apiKey", "abc123");
await ctx.kv.delete("settings:apiKey");

注意

对于用户可配置的值，使用 settings: 前缀；对于内部插件状态，使用 state: 前缀。

自定义表 → 存储集合

WordPress

global $wpdb;
$table = $wpdb->prefix . 'my_plugin_items';

// Insert
$wpdb->insert($table, ['name' => 'Item 1', 'status' => 'active']);

// Query
$items = $wpdb->get_results(
"SELECT \* FROM $table WHERE status = 'active' LIMIT 10"
);

EmDash

// Declare in plugin definition
storage: {
    items: {
        indexes: ["status", "createdAt"],
    },
},

// In hooks or routes:
await ctx.storage.items.put("item-1", {
    name: "Item 1",
    status: "active",
    createdAt: new Date().toISOString(),
});

const result = await ctx.storage.items.query({
    where: { status: "active" },
    limit: 10,
});

设置模式

WordPress 使用 Settings API 来管理面板表单。EmDash 使用声明式模式，可自动生成用户界面。

WordPress

add_action('admin_init', function() {
    register_setting('my_plugin', 'my_plugin_api_key');
    add_settings_section('main', 'Settings', null, 'my-plugin');
    add_settings_field('api_key', 'API Key', function() {
        $value = get_option('my_plugin_api_key');
        echo '<input type="text" name="my_plugin_api_key"
              value="' . esc_attr($value) . '">';
    }, 'my-plugin', 'main');
});

EmDash

admin: {
    settingsSchema: {
        apiKey: {
            type: "secret",
            label: "API Key",
            description: "Your API key from the dashboard",
        },
        enabled: {
            type: "boolean",
            label: "Enabled",
            default: true,
        },
        limit: {
            type: "number",
            label: "Item Limit",
            default: 100,
            min: 1,
            max: 1000,
        },
    },
}

管理界面

WordPress 管理页面使用 PHP。EmDash 使用 React 组件。

src/admin.tsx

import { useState, useEffect } from "react";

export const widgets = {
  summary: function SummaryWidget() {
    const [count, setCount] = useState(0);

    useEffect(() => {
      fetch("/_emdash/api/plugins/my-plugin/status")
        .then((r) => r.json())
        .then((data) => setCount(data.count));
    }, []);

    return <div>Total items: {count}</div>;
  },
};

export const pages = {
  settings: function SettingsPage() {
    // React component for settings page
    return <div>Settings content</div>;
  },
};

在插件定义中注册：

src/index.ts

admin: {
    entry: "@my-org/my-plugin/admin",
    pages: [{ path: "/settings", label: "Dashboard" }],
    widgets: [{ id: "summary", title: "Summary", size: "half" }],
},

REST API → 插件路由

WordPress

register_rest_route('my-plugin/v1', '/items', [
    'methods' => 'GET',
    'callback' => function($request) {
        global $wpdb;
        $items = $wpdb->get_results("SELECT * FROM items LIMIT 50");
        return new WP_REST_Response($items);
    },
]);

EmDash

routes: {
    items: {
        handler: async (ctx) => {
            const result = await ctx.storage.items.query({ limit: 50 });
            return { items: result.items };
        },
    },
},

路由可通过 /_emdash/api/plugins/{plugin-id}/{route-name} 访问。

移植流程

1. 分析 WordPress 插件

   记录其功能：钩子、数据库操作、管理页面、REST 端点。

2. 映射到 EmDash 概念

   WordPress 钩子 → EmDash 钩子。wp_options → ctx.kv。自定义表 → 存储集合。管理页面 → React 组件。REST 端点 → 插件路由。

3. 创建插件骨架

   src/index.ts

   import { definePlugin } from "emdash";
   
   export function createPlugin() {
   return definePlugin({
     id: "my-ported-plugin",
     version: "1.0.0",
     capabilities: [],
     storage: {},
     hooks: {},
     routes: {},
     admin: {},
   });
   }

4. 按顺序实现

   存储 → 钩子 → 管理界面 → 路由

5. 全面测试

   验证钩子是否正确触发、存储是否正常工作以及管理界面是否正确渲染。

示例：阅读时间插件

WordPress

add_filter('wp_insert_post_data', function($data, $postarr) {
    if ($data['post_type'] !== 'post') return $data;

    $content = strip_tags($data['post_content']);
    $word_count = str_word_count($content);
    $read_time = ceil($word_count / 200);

    if (!empty($postarr['ID'])) {
        update_post_meta($postarr['ID'], '_read_time', $read_time);
    }
    return $data;

}, 10, 2);

EmDash

src/index.ts

export function createPlugin() {
    return definePlugin({
        id: "read-time",
        version: "1.0.0",

        admin: {
            settingsSchema: {
                wordsPerMinute: {
                    type: "number",
                    label: "Words per minute",
                    default: 200,
                    min: 100,
                    max: 400,
                },
            },
        },

        hooks: {
            "content:beforeSave": async (event, ctx) => {
                if (event.collection !== "posts") return;

                const wpm = await ctx.kv.get<number>("settings:wordsPerMinute") ?? 200;
                const text = JSON.stringify(event.content.body || "");
                const readTime = Math.ceil(text.split(/\s+/).length / wpm);

                return { ...event.content, readTime };
            },
        },
    });
}

AI 辅助移植

插件移植比主题移植更微妙，但 AI 助手仍然能提供显著帮助。提供 WordPress 插件代码以及 EmDash 的插件 API 文档，助手可以生成一个合理的初稿。复杂的插件可能需要多次迭代。

能力

插件必须声明所需的能力，以实现安全沙箱：

能力	提供功能	使用场景
network:fetch	ctx.http.fetch()	外部 API 调用
read:content	ctx.content.get(), list()	读取 CMS 内容
write:content	ctx.content.create() 等	修改内容
read:media	ctx.media.get(), list()	读取媒体
write:media	ctx.media.getUploadUrl()	上传媒体

常见陷阱

无全局状态 — 使用存储而非全局变量。

一切都是异步的 — 始终 await 存储和 API 调用。

无直接 SQL — 使用结构化存储集合。

无文件系统访问 — 使用媒体 API 处理文件。

后续步骤

• 钩子参考 — 所有钩子及其签名
• 存储 API — 集合和查询
• 设置 — 设置模式和键值存储
• 管理界面 — 构建管理页面