工坊测试插件开发进度

sch246

安装NodeJS

下载并解压

wget https://nodejs.org/dist/v22.12.0/node-v22.12.0-linux-x64.tar.xz
tar xvJf node-v22.12.0-linux-x64.tar.xz
mv node-v22.12.0-linux-x64 /usr/local/node-v22.12.0

设置PATH

echo 'export PATH=$PATH:/usr/local/nodejs/bin' >> /etc/bash.bashrc && source /etc/bash.bashrc

创建脚本nano /usr/local/node-v22.12.0/link_nodejs.sh

用于设置该版本到path

#!/bin/bash

# 获取脚本所在的目录
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# 检查目标目录是否存在，如果不存在则创建
if [ ! -d "/usr/local/nodejs/" ]; then
    sudo mkdir -p "/usr/local/nodejs/"
fi

# 源目录和目标目录
SOURCE_DIR="$SCRIPT_DIR/bin"
TARGET_DIR="/usr/local/nodejs/bin"

# 清除原有的bin
if [ -d "$TARGET_DIR" ]; then
    rm "$TARGET_DIR"
fi

# 创建软链接
sudo ln -s "$SOURCE_DIR" "$TARGET_DIR"

运行脚本

cd /usr/local/node-v22.12.0
chmod +x link_nodejs.sh
./link_nodejs.sh

安装yarn

要管理包有许多更好的选择，，例如pnpm或者bun，用yarn单纯是因为CLI里面也用的yarn，这样能少安装一个包管理器（先是安装到了pnpm然后又退回来卸了）

npm install -g yarn

按照教程进行

要命的是我也不记得从哪里找到的步骤了，，不过问题不大

接下来的步骤都需要在www-data用户下进行（运行flarum的用户），不然包安装的地方www-data没权限使用（是的，又是一次踩坑）

sudo -u www-data -s

安装webpack 和 Flarum CLI 2.0

需要注意版本对应，比如工坊论坛目前是1.x，那么就需要安装2.0.0的CLI

对应关系在CLI的github链接里有

yarn global add webpack
yarn global add @flarum/cli@^2.0.0

运行flarum-cli试试

发现没法全局运行——

看到用户目录/var/www/下有个.yarn/bin所以添加到全局变量

echo 'export PATH=$PATH:/var/www/.yarn/bin' >> ~/.bashrc && source ~/.bashrc

OK了。前期准备完成。

创建插件

这里有教程

虽然用CLI能够很快创建模板，但是手动搭一遍有助于获得对扩展的整体认知，使用CLI也能更好

然后你就会发现CLI还是有很多看不懂的选项

我们首先需要一个开发的地方， cd 到 flarum 根目录运行以下命令

composer config repositories.0 path "packages/*"

它会在conposer.json的末尾添加这个东西

{
  // 其它内容...
    "repositories": [{
            "type": "path",
            "url": "packages/*"
        }]
}

这样 composer 就会在这个路径找拓展了

在 flarum 根目录创建 packages 文件夹并 cd 进去，运行 CLI 创建新项目

mkdir packages
cd packages
flarum-cli init test

（这里的名字test只决定文件夹的名字）

照着提示填填，看不懂的直接回车取默认值，虽然不知道为什么 git init 选 yes 会报错不过问题不大

我这里设置了 id 是 sch246/flarum-test （注意必须以flarum-开头）

它会在当前目录（也就是packages）下创建 test文件夹，扩展的核心就两个文件

composer.json 扩展的元信息，存储它的名字，id，关键词，作者和联系方式，版本，开源协议，图标，依赖，脚本，等等，主要是给 flarum 看的
extend.php 扩展代码的入口

由于未知原因我创建时extend.php里是这样的：namespace Sch246\\\\Test;

这应该是bug，实际上只能写namespace Sch246\Test;，改回来就好了

接下来 cd 到 flarum 根目录，将这个扩展以开发模式添加到 flarum

composer require sch246/flarum-test *@dev

只需要输入之前在 CLI 设置的 id sch246/flarum-test， composer 会自己找到扩展

仪表盘上应该出现新的扩展，启用它，刷新页面，此时 f12 打开开发者控制台，应该能看到一句 hello world

[sch246/flarum-test] Hello, admin!

具体是什么取决于打开的是后台还是前台，它来自于extend.php里导入的js/dist/forum.js或者js/dist/admin.js

而这两个 js 来自于扩展文件夹下 js/src/forum/index.ts 或 js/src/admin/index.ts 的生成

每次更改都需要 cd 进去 build 一下，然后再到根目录清除缓存以应用，挺麻烦的

cd /var/www/flarum/packages/test/js && yarn build
cd /var/www/flarum && php flarum cache:clear

按照教程修改扩展的extend.php，hello world 应该能运行

<?php

/*
 * This file is part of sch246/flarum-test.
 *
 * Copyright (c) 2024 sch246.
 *
 * For the full copyright and license information, please view the LICENSE.md
 * file that was distributed with this source code.
 */

namespace Sch246\Test;

use Flarum\Extend;
use Flarum\Frontend\Document; // 添加这一行以导入 Document 类

return [
    
    (new Extend\Frontend('forum'))
        ->content(function (Document $document) {
            $document->head[] = '<script>alert("Hello, world!")</script>';
        }),

];

如果崩溃，那么可能是语法错误或者缺少导入（比如缺少use Flarum\Frontend\Document;）

如果没有反应（包括f12控制台也没有log输出），可以检查网站源代码部分，看看里面有没有把你的代码传输过来

没有的话就是需要手动清除网站缓存，到 flarum 根目录运行php flarum cache:clear（前面有）

到这里为之可以开始开发插件了——（麻烦死了）

sch246

黑幕！

flarum 本身有一个黑幕功能，但是点击后就消失掉了，很没意思

我们接下来要实现这个功能（对的，萌娘百科上的功能）

简单起见，我选择替换原有的黑幕

检查

阉割版可以用单纯的 css 实现

span.spoiler {
    color: transparent !important;
    background: var(--text-color) !important;
    transition: color 0.1s linear !important;
}

span.spoiler:hover {
    color: var(--tag-bg) !important;
}

span.spoiler a {
    color: transparent !important;
    background: var(--text-color) !important;
    transition: color 0.1s linear !important;
}

span.spoiler a:hover {
    color: var(--link-color) !important;
}

但是这无法实现悬浮显示文字和点击后不消失

检查发现消失来自于onclick，它会移除 class 导致元素变回普通元素

<span class="spoiler" onclick="removeAttribute('class')">黑幕啊黑幕！</span>

所以需要 js 的帮助，而添加<script>并不会在合适的时候加载，所以最好使用插件

用前面的步骤创建插件（这里的插件 id 是sch246/flarum-test），打开插件根目录下js/src/forum/index.ts

import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import Discussion from 'flarum/forum/components/CommentPost';

app.initializers.add('sch246/flarum-test', () => {
  // console.log('[sch246/flarum-test] Hello, forum!');
  extend(Discussion.prototype, 'oncreate', function() {
    // 在每次加载讨论内容后，执行代码
    this.$('.spoiler').each(function() {
      $(this).removeAttr('onclick');
      $(this).attr("title", "你知道的太多了");
    });
  });
});

要确定代码什么时候加载，就得找到对的组件'flarum/forum/components/CommentPost';

怎么找到呢，问ai这个需要挂载什么，然后去api里面搜

这里是官方教程

1.8.0的api在这里

然后把 css 写入 less/forum.less

build 并且清除缓存

sch246

替换点赞和回复为图片

我们要实现的是这个

单纯添加或替换图片很简单，用 css 就可以

// 隐藏回复字样
.item-reply .Button .Button-label {
    display:none;
}
// 隐藏点赞字样
.item-like .Button .Button-label {
    display:none;
}

// 回复按钮带图标
.item-reply .Button:before {
    font-family: 'Font Awesome 6 Free';
    font-weight: 600;
    font-size: 15px;
    content: '\f3e5';
    margin-right: 8px;
}

// 点赞按钮带图标
.item-like .Button:before {
    font-family: 'Font Awesome 6 Free';
    font-weight: 600; // 填400就是空心的
    font-size: 15px;
    content:  '\f164';
    margin-right: 8px;
}

但是如果需要点赞能够变化图标的实心/空心，就需要用插件了

用 cli 创建插件sch246/flarum-awesome-like

在 composer.json 里添加上依赖

{
    "require": {
        "flarum/likes": "*"
    }
}

检查

为了实现点赞变化图标，我们需要

获取点赞状态
获取元素对象
根据状态给元素增减类
设置 css 根据类显示不同状态

由于点赞不属于核心功能，官方 api 里没有，我们需要找到点赞插件的库

注意到渲染点赞状态的代码在js/src/forum/addLikeAction.js

import { extend } from 'flarum/common/extend';
import app from 'flarum/forum/app';
import Button from 'flarum/common/components/Button';
import CommentPost from 'flarum/forum/components/CommentPost';

export default function () {
  extend(CommentPost.prototype, 'actionItems', function (items) {
    const post = this.attrs.post;

    if (post.isHidden() || !post.canLike()) return;

    const likes = post.likes();

    let isLiked = app.session.user && likes && likes.some((user) => user === app.session.user);

    items.add(
      'like',
      <Button
        className="Button Button--link"
        onclick={() => {
          isLiked = !isLiked;

          post.save({ isLiked });

          // We've saved the fact that we do or don't like the post, but in order
          // to provide instantaneous feedback to the user, we'll need to add or
          // remove the like from the relationship data manually.
          const data = post.data.relationships.likes.data;
          data.some((like, i) => {
            if (like.id === app.session.user.id()) {
              data.splice(i, 1);
              return true;
            }
          });

          if (isLiked) {
            data.unshift({ type: 'users', id: app.session.user.id() });
          }
        }}
      >
        {app.translator.trans(isLiked ? 'flarum-likes.forum.post.unlike_link' : 'flarum-likes.forum.post.like_link')}
      </Button>
    );
  });
}

获取点赞状态

    const likes = post.likes();

    let isLiked = app.session.user && likes && likes.some((user) => user === app.session.user);

注意到它在前端存储了点赞状态：

          post.save({ isLiked });

我们看看能不能读出来，查看 post 的 api

post 是 CommentPost.attrs.post ，从CommentPost开始一顿点找到是Post，也就是flarum/common/models/Post

因此我们应该可以用这个来获取isLiked

const isLiked = post.attribute('isLiked');

获取元素对象

查看 html 得出 jQuery 对象

const likeButton = this.$('.item-like .Button');

根据状态给元素增减类

我们需要每次点击时都更新状态，因此使用view

组合得到代码js/src/forum/index.ts

import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import CommentPost from 'flarum/forum/components/CommentPost';

app.initializers.add('sch246/flarum-awesome-like', () => {
  extend(CommentPost.prototype, 'view', function () {
      const likeButton = this.$('.item-like .Button');
      const post = this.attrs.post;
      const isLiked = post.attribute('isLiked');
      likeButton.toggleClass('active', !!isLiked);
  }
}

设置 css 根据类显示不同状态

less/forum.less

// 点赞按钮带图标
.item-like .Button {
    &:before {
        font-weight: 400;
        content: '\f164';
        font-family: 'Font Awesome 6 Free';
        font-size: 15px;
        margin-right: 8px;
    }

    &.active:before {
        font-weight: 600;
        vertical-align: -1px;
    }
}

问题

发现在第一次点击之前总是不变化，检查发现是因为 post.save({ isLiked }); 仅在第一次按下后才运行

也就是在之前都是没有存储 isLiked 的

最终采用的方案是，既然需要这个属性，那我 create 时运行一遍不就行了

import Post from 'flarum/common/models/Post';
import User from 'flarum/common/models/User';

export interface IPost extends Post {
  isHidden: () => boolean;
  canLike: () => boolean;
  likes: () => Array<User>;
}

无视风险，继续运行

import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import CommentPost from 'flarum/forum/components/CommentPost';
import { IPost } from './IPost'

app.initializers.add('sch246/flarum-awesome-like', () => {
  extend(CommentPost.prototype, 'oncreate', function () {
    // 同步isLiked
    const post = this.attrs.post as IPost;
    if (post.isHidden() || !post.canLike()) return;
    const likes = post.likes();
    const isLiked = app.session.user && likes && likes.some((user) => user === app.session.user) || false;
    post.save({isLiked})
  });
}

sch246

替换点赞和回复为图片

插件配置

我希望增加插件配置，能够控制回复和点赞图标是否显示/是否仅图标

官方教程

官方这个教程教的不是很完整（

只教了设置，没有教怎么从前端获取的样子

实际上在后面的章节有

英文版教程在这里

注册后台设置

我们先创建后台的设置js/src/admin/index.ts

import app from 'flarum/admin/app';

app.initializers.add('sch246/flarum-awesome-like', () => {
  // console.log('[sch246/flarum-awesome-like] Hello, admin!');

  
  app.extensionData
    .for('sch246-awesome-like')
    .registerSetting(
      {
        setting: 'sch246-awesome-like.like',
        label: app.translator.trans('sch246-awesome-like.admin.like_label'),
        type: 'select',
        options: {
          'off': app.translator.trans('sch246-awesome-like.admin.off'),
          'on': app.translator.trans('sch246-awesome-like.admin.on'),
          'only': app.translator.trans('sch246-awesome-like.admin.only'),
        },
        default: 'only',
      }
    )
    .registerSetting(
      {
        setting: 'sch246-awesome-like.reply',
        label: app.translator.trans('sch246-awesome-like.admin.reply_label'),
        type: 'select',
        options: {
          'off': app.translator.trans('sch246-awesome-like.admin.off'),
          'on': app.translator.trans('sch246-awesome-like.admin.on'),
          'only': app.translator.trans('sch246-awesome-like.admin.only'),
        },
        default: 'only',
      }
    )
});

把英语的语言文件locale/en.yml填了，然后填中文的

创建语言文件locale/zh-Hans.yml

sch246-awesome-like:
  # For more details on the format
  # Checkout https://docs.flarum.org/extend/i18n/#appendix-a-standard-key-format
  admin:
    like_label: 点赞图标
    reply_label: 回复图标
    off: 禁用
    on: 启用
    only: 仅图标


  forum:

此时应该能在后台正常显示设置

创建接口

接口在 Extend\Settings 创建

在这里查看：官方api文档

打开extend.php加上些东西

namespace Sch246\FlarumAwesomeLike;

use Flarum\Extend;

return [
    (new Extend\Frontend('forum'))
        ->js(__DIR__.'/js/dist/forum.js')
        ->css(__DIR__.'/less/forum.less'),
    (new Extend\Frontend('admin'))
        ->js(__DIR__.'/js/dist/admin.js')
        ->css(__DIR__.'/less/admin.less'),
    new Extend\Locales(__DIR__.'/locale'),


    (new Extend\Settings())
        ->serializeToForum('sch246-awesome-like-like', 'sch246-awesome-like.like')
        ->serializeToForum('sch246-awesome-like-reply', 'sch246-awesome-like.reply')
];

serializeToForum第一个参数给前端用的(attributeName)，第二个参数是后台设置的id

前端访问设置，改变属性

然后略加修改，把值赋到属性上

import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import CommentPost from 'flarum/forum/components/CommentPost';

app.initializers.add('sch246/flarum-awesome-like', () => {
  let replySetting: string;
  let likeSetting: string;

  extend(CommentPost.prototype, 'oncreate', function () {

    // 根据设置改变attr
    replySetting = app.forum.attribute('sch246-awesome-like-reply');
    const replyButton = this.$('.item-reply .Button');
    replyButton.attr('icon', replySetting);

    // 根据设置改变attr
    likeSetting = app.forum.attribute('sch246-awesome-like-like');
    const likeButton = this.$('.item-like .Button');
    likeButton.attr('icon', likeSetting);

  });

});

css根据属性切换显示

// 通用样式
.Button[icon=on]:before,
.Button[icon=only]:before {
    font-family: 'Font Awesome 6 Free';
    font-size: 15px;
    margin-right: 8px;
}

.Button[icon=only] .Button-label {
    display:none;
}

// 回复按钮带图标
.item-reply {
    .Button[icon=on]:before,
    .Button[icon=only]:before {
        font-weight: 600;
        content: '\f3e5';
    }
    .Button[icon=only]:before {
        margin-right: 0;
    }
}

// 点赞按钮带图标
.item-like {
    .Button[icon=on],
    .Button[icon=only] {
        &:before {
            font-weight: 400;
            content: '\f164';
        }
    
        &.active:before {
            font-weight: 600;
            vertical-align: -1px;
        }
    }
}

加一点细节

可以在仅显示图标时，让鼠标移上去显示按钮名字

以下是js\src\forum\index.ts的整体代码

import app from 'flarum/forum/app';
import { extend } from 'flarum/common/extend';
import CommentPost from 'flarum/forum/components/CommentPost';
import { IPost } from './IPost';

app.initializers.add('sch246/flarum-awesome-like', () => {
  let replySetting: string;
  let likeSetting: string;

  extend(CommentPost.prototype, 'oncreate', function () {

    // 根据设置改变attr
    replySetting = app.forum.attribute('sch246-awesome-like-reply');
    const replyButton = this.$('.item-reply .Button');
    replyButton.attr('icon', replySetting);

    // 根据设置改变attr
    likeSetting = app.forum.attribute('sch246-awesome-like-like');
    const likeButton = this.$('.item-like .Button');
    likeButton.attr('icon', likeSetting);

    // 同步isLiked
    const post = this.attrs.post as IPost;
    if (post.isHidden() || !post.canLike()) return;
    const likes = post.likes();
    const isLiked = app.session.user && likes && likes.some((user) => user === app.session.user) || false;
    post.save({isLiked})
  });


  extend(CommentPost.prototype, 'view', function () {
    if (replySetting!=='off') {
      const replyButton = this.$('.item-reply .Button');

      setTimeout(() => { // 延迟更新
        if (replySetting === 'only') {
          replyButton.attr('title', replyButton.children().eq(0).html());
        }
      }, 0);

    };

    if (likeSetting!=='off') {
      const likeButton = this.$('.item-like .Button');
      const post = this.attrs.post;
      const isLiked = post.attribute('isLiked');
      likeButton.toggleClass('active', !!isLiked);

      setTimeout(() => { // 延迟更新
        if (likeSetting === 'only') {
          likeButton.attr('title', likeButton.children().eq(0).html());
        }
      }, 0);

    };
  });

});