通过实践学习 TDD:在 Umbraco 的富文本编辑器中标记成员
在我正在构建的系统中,我需要能够在网站的文本中提及 umbraco 成员。为此,我需要构建 umbraco 富文本编辑器的扩展:tinymce。
语境
作为内容编辑者,我想在消息或文章中标记成员,以便他们收到有关他们的新内容的通知。
我研究了类似的实现,例如 slack 或 x 上的实现。slack 在编写过程中使用特殊的 html 标签进行提及,然后使用特定格式的令牌将数据发送到后端。我决定采取类似的方法,但现在忘记翻译步骤。在内容中,提及将如下所示:
<mention user-id="1324" class="mcenoneditable">@d_inventor</mention>
初步探索
在开始构建之前,我一直在寻找连接 umbraco 中的 tinymce 的方法。这是我最不喜欢在 umbraco 后台扩展的事情之一。不过我之前已经这样做过,并且我发现如果我在 angularjs 中的 umbraco 的tinymceservice 上创建一个装饰器,扩展编辑器是最简单的。在 tinymce 的文档中,我发现了一个名为“autocompleters”的功能,它完全满足了我的需要,因此我可以使用编辑器。我的初始代码(尚未进行任何测试)如下所示:
rtedecorator.$inject = ["$delegate"];export function rtedecorator($delegate: any) { const original = $delegate.initializeeditor; $delegate.initializeeditor = function (args: any) { original.apply($delegate, arguments); args.editor.contentstyles.push("mention { background-color: #f7f3c1; }"); args.editor.ui.registry.addautocompleter("mentions", { trigger: "@", fetch: ( pattern: string, maxresults: number, _fetchoptions: record<string unknown> ): promise<imceautocompleteitem> // todo: fetch from backend => promise.resolve([{ type: "autocompleteitem", value: "1234", text: "d_inventor" }]), onaction: (api: any, rng: range, value: string): void => { // todo: business logic api.hide(); }, }); }; return $delegate;}</imceautocompleteitem></string>
我在这个项目中使用了 vite 和 typescript,但我没有安装任何 tinymce 类型。现在我会保留any并尽可能避免tinymce。
使用 tdd 进行构建
我决定使用 jest 进行测试。我发现入门很简单,并且很快就成功了。
✅ success |
---|
i learned a new tool for unit testing in frontend code. i succesfully applied the tool to write a frontend with unit tests |
我编写了第一个测试:
提及-manager.test.ts
describe("mentionsmanager.fetch", () => { let sut: mentionsmanager; let items: imention[]; beforeeach(() => { items = []; sut = new mentionsmanager(); }); test("should be able to fetch one result", async () => { items.push({ userid: "1234", username: "d_inventor" }); const result = await sut.fetch(1); expect(result).tohavelength(1); });});
typescript 编译器的严格性让我有些惊讶。此处的分步操作实际上意味着不添加任何您尚未实际使用的内容。例如,我想添加对“ui”的引用,因为我知道稍后会使用它,但在使用构造函数中放入的所有内容之前,我实际上无法编译 mentionsmanager。
经过几轮红、绿和重构,我最终得到了这些测试:
提及-manager.test.ts
describe("mentionsmanager.fetch", () => { let sut: mentionsmanager; let items: imention[]; beforeeach(() => { items = []; sut = new mentionsmanager(() => promise.resolve(items)); }); test("should be able to fetch one result", async () => { items.push({ userid: "1234", username: "d_inventor" }); const result = await sut.fetch(1); expect(result).tohavelength(1); }); test("should be able to fetch empty result", async () => { const result = await sut.fetch(1); expect(result).tohavelength(0); }); test("should be able to fetch many results", async () => { items.push({ userid: "1324", username: "d_inventor" }, { userid: "3456", username: "d_inventor2" }); const result = await sut.fetch(2); expect(result).tohavelength(2); }); test("should return empty list upon error", () => { const sut = new mentionsmanager(() => { throw new error("something went wrong while fetching"); }, {} as imentionsui); return expect(sut.fetch(1)).resolves.tohavelength(0); });});
有了这个逻辑,我就可以从任何来源获取提及并通过“fetch”挂钩在 rte 中显示它们。
我使用相同的方法创建一个“pick”方法来获取选定的成员并将提及插入到编辑器中。这是我最终得到的代码:
提及-manager.ts
export class MentionsManager { private mentions: IMention[] = []; constructor( private source: MentionsAPI, private ui: IMentionsUI ) {} async fetch(take: number, query?: string): Promise<imention> { try { const result = await this.source(take, query); if (result.length === 0) return []; this.mentions = result; return result; } catch { return []; } } pick(id: string, location: Range): void { const mention = this.mentions.find((m) => m.userId === id); if (!mention) return; this.ui.insertMention(mention, location); }}</imention>
❓ uncertainty |
---|
the range interface is a built-in type that is really difficult to mock and this interface leaks an implementation detail into my business logic. i feel like there might've been a better way to do this. |
回顾
总的来说,我认为我最终得到了易于更改的简单代码。这段代码中仍有一些部分我不太喜欢。我希望业务逻辑来驱动 ui,但代码最终更像是一个简单的商店,它也对 ui 进行了一次调用。我想知道是否可以更牢固地包装 ui,以便更好地利用管理器。