林晓lx的个人Blog 登高现红日，实践出真知！ 2025-09-24T16:30:02.650Z https://blog.matoapp.net/ 林晓lx Hexo [学习笔记]使用git rebase做分支差异化同步 https://blog.matoapp.net/posts/535a3e30/ 2025-06-05T10:04:00.000Z 2025-09-24T16:30:02.650Z 在一个.NET 项目中，使用了Volo.Abp库，但出于某种原因，需要源码调试，因此，使用源码方式集成的项目做了一个分支archive-abp-source

其中引用方式变更操作的提交为：7de53907

后续，在master分支中，又新增了若干个提交，现在的目标是：把 master 分支中后续的所有提交，除了 7de53907... 这个 commit，合并到archive-abp-source分支。

这在 Git 中不是一个“标准的 merge”操作（Git merge 默认会把所有 commit 都合并）。不过，可以通过以下步骤达成这个目的：

基于 master 创建临时分支

1
2
git checkout master
git checkout -b temp-merge

使用交互式 rebase 删除指定提交

1
git rebase -i --rebase-merges <common-base-commit>

common-base-commit 是当前分支与 master 的共同祖先，比如用 git merge-base master archive-abp-source 找到。结果就是 <common-base-commit>，可用于 rebase -i 时指定起点。

如果你知道数量，也可以简单地 rebase 最近 20 次提交：

git rebase -i HEAD~20

然后在打开的编辑器中把 7de53907... 那一行改为 drop，保存退出即可。

切回目标分支，执行合并

1
2
3
git checkout archive-abp-source
git merge temp-merge

[可选]删除临时分支

git branch -d temp-merge
]]> 文章介绍了如何在Git中将master分支中除特定提交外的其他提交合并到archive-abp-source分支，通过创建临时分支、使用交互式rebase删除指定提交，再合并回目标分支的操作步骤。 [学习笔记] 从零开始虚拟化搭建数据库服务器 https://blog.matoapp.net/posts/b60d95fe/ 2025-06-05T10:03:00.000Z 2025-09-24T16:30:02.634Z [toc]

一. 创建虚拟机并安装CentOS 7

硬件参数根据需求进行设置

CD/DVD 源选择CentOS7的 ISO 镜像

安装过程略..

二. 安装VMware Tools

等待安装结束，从菜单中选择安装VMware Tools，此时
CD/DVD 源会自动挂载到虚拟机中。

从虚拟机进入CentOS 7 系统

运行，创建挂载目录

1
2
sudo mkdir -p /mnt/cdrom

运行

1
2
lsblk

查看CD/DVD驱动器设备：

运行命令，挂载CD/DVD驱动器

1
2
sudo mount /dev/sr0 /mnt/cdrom

执行结果如下，表明挂载成功

进入挂载目录，解压VMware Tools安装包

1
2
3
cp /mnt/cdrom/VMwareTools-*.tar.gz /tmp/
cd /tmp
tar -zxvf VMwareTools-*.tar.gz

如果缺少编译工具和内核头文件，可以运行以下命令安装：

1
yum install -y gcc make perl kernel-devel kernel-headers

进入解压后的目录，运行以下命令安装VMware Tools：

1
2
cd vmware-tools-distrib
sudo ./vmware-install.pl

执行一路回车即可，安装完成后会提示：

安装成功结果：

三. 安装常用工具

确保联网

当前没有任何网络工具，如何确定系统已经接入互联网？

以访问百度为例，运行以下命令：

1
2
echo > /dev/tcp/www.baidu.com/80 && echo "ok" || echo "not ok"

显示ok，则表明已经联网。

因为CentOS7已停止维护，所以需要手动添加 repo 源。运行：

安装网络工具

1
2

yum install -y wget curl net-tools vim epel-release

配置网络

将虚拟机自动获取的IP地址改为静态IP地址。

开放ssh的22端口

打开sshd

1
2
sudo systemctl start sshd
sudo systemctl enable sshd

打开防火墙，运行

1
2
3
sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --reload

运行结结果：

此时可以通过ssh登录了，接下来可以安装SQL-Server、Redis等服务。

四. 安装服务

配置SELinux，打开码编辑器，并将SELINUX=enforcing 改为 SELINUX=permissive

1
vi /etc/selinux/config

安装 SQL Server 2017

1
2
3
4
5
6
7
sudo curl -o /etc/yum.repos.d/mssql-server.repo https://packages.microsoft.com/config/rhel/7/mssql-server-2017.repo
sudo yum install -y mssql-server
sudo /opt/mssql/bin/mssql-conf setup
sudo firewall-cmd --zone=public --add-port=1433/tcp --permanent
sudo firewall-cmd --reload
systemctl status mssql-server
systemctl enable mssql-server

安装 OpenSSL

1
2
3
4
5
6
7
8
9
10
wget https://www.openssl.org/source/openssl-1.1.1.tar.gz
tar -xvf openssl-1.1.1.tar.gz
cd openssl-1.1.1
./config --prefix=/usr/local/openssl shared zlib
make && make install
sudo ldconfig
ln -s /usr/local/openssl/bin/openssl /usr/bin/openssl
ln -s /usr/local/openssl/lib/libssl.so.1.1 /usr/lib64/libssl.so.1.1
ln -s /usr/local/openssl/lib/libcrypto.so.1.1 /usr/lib64/libcrypto.so.1.1

安装 Redis

1
2
3
4
5
6
7
tar -zxvf redis-7.4.0.tar.gz
cd redis-7.4.0
make && make install
ln -s /usr/local/bin/redis-server /usr/bin/redis-server
cp redis.conf /etc/redis/
sudo firewall-cmd --zone=public --add-port=6379/tcp --permanent
sudo firewall-cmd --reload

新建redis启动脚本

1
vi /usr/lib/systemd/system/redis.service
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[Unit]
Description=Redis persistent key-value database
After=network.target

[Service]
LimitNOFILE=10032
ExecStart=/usr/bin/redis-server /etc/redis/redis.conf --supervised systemd
ExecStop=/usr/libexec/redis-shutdown
Type=simple
User=redis
Group=redis
RuntimeDirectory=redis
RuntimeDirectoryMode=0755

[Install]
WantedBy=multi-user.target

执行命令

1
2
3
4
5

systemctl daemon-reload
systemctl start redis
systemctl enable redis

安装 RabbitMQ

安装Erlang

1
2
3
4
cd /tmp/
curl -sfL -O https://github.com/rabbitmq/erlang-rpm/releases/download/v26.2.5.11/erlang-26.2.5.11-1.el7.x86_64.rpm
yum install -y erlang-26.2.5.11-1.el7.x86_64.rpm

安装RabbitMQ

1
2
3
curl -sfL -O https://github.com/rabbitmq/rabbitmq-server/releases/download/v4.1.0/rabbitmq-server-4.1.0-1.el8.noarch.rpm
yum install rabbitmq-server-4.1.0-1.el8.noarch.rpm

添加防火墙

1
2
3
4
5
sudo firewall-cmd --zone=public --add-port=5672/tcp --permanent

sudo firewall-cmd --zone=public --add-port=25672/tcp --permanent

sudo firewall-cmd --zone=public --add-port=4369/tcp --permanent

配置外部访问的用户

1
2
3
4
5
6
7
8
9
# 1. 添加用户 sa，并设置密码（将 yourpassword 替换成你实际使用的密码）
sudo rabbitmqctl add_user sa yourpassword

# 2. 给用户 sa 设置为管理员角色
sudo rabbitmqctl set_user_tags sa administrator

# 3. 设置该用户对默认虚拟主机 "/" 拥有全部权限
sudo rabbitmqctl set_permissions -p / sa ".*" ".*" ".*"

启动RabbitMQ的Web管理插件

1
2
3
4
sudo rabbitmq-plugins list | grep management
sudo rabbitmq-plugins enable rabbitmq_management
sudo systemctl restart rabbitmq-server

运行结果：

访问RabbitMQ管理界面，默认地址为 http://127.0.0.1:15672，使用刚才创建的用户 sa 和密码登录。

..

]]> 文章介绍了在VMware中创建CentOS 7虚拟机、安装VMware Tools、配置网络、安装常用工具及SQL Server、OpenSSL、Redis和RabbitMQ等服务的详细步骤。 开箱即用的.NET MAUI组件库 V-Control 发布了! https://blog.matoapp.net/posts/a4f268b/ 2025-02-06T18:04:00.000Z 2025-09-24T16:30:02.710Z 之前写过挺多的MAUI Sample，其中有很多代码可以打包成组件，当组件完善到一定程度，我会把控件封装起来放到控件库中。

今天，在这个仓库建立一年零八个月后，我觉得可以考虑将其作为开源库发布。

有很多网友在观望.NET MAUI，犹豫是否可以拿来作为有生产力的跨平台移动端开发工具，此时我想告诉大家，.NET MAUI是一个非常不错的移动开发平台。配合 V-Control 来构建移动应用程序，V-Control是适用于.NET MAUI 的组件库(Component)，它提供了一组开箱即用的 UI 控件，可快速搭建面向业务的应用程序界面。

功能

Todo

  • VAutocomplete - 自动完成组件
  • VComparisonView - 比较视图组件
  • VCalendar - 日历组件
  • 暗黑模式
  • 基于 BlazorApp 的组件

快速开始

  1. 在你的.NET MAUI 项目中执行以下命令来安装 V-Control：
1
dotnet add package VControl

或在NUGET中搜索”V-Control”并安装它。

  1. 在 MauiProgram 使用.UseVControl()在MauiAppBuilder中添加V-Control的处理程序。
1
2
3
4
5
6
7
8
9
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .UseVControl()   //在这里添加V-Control的处理程序
    var mauiApp = builder.Build();
    return mauiApp;
}
  1. 打开 App.xaml 文件， 在资源中添加<v:VControlTheme />。
1
2
3
4
5
6
7
8
9
10
11

<?xml version = "1.0" encoding = "UTF-8" ?>
<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:v="clr-namespace:VControl.Styles;assembly=VControl">
    <Application.Resources>
        <v:VControlTheme />
        ...
    </Application.Resources>   
</Application>

文档

前往V-Control Docs

源码和示例

您可以前往GitHub查看V-Control的源码和示例。

]]> 文章介绍了V-Control组件库，这是一个为.NET MAUI设计的UI组件库，提供多种开箱即用的控件，方便快速开发移动应用。作者在仓库建立一年零八个月后决定将其开源，旨在展示.NET MAUI作为生产力工具的可行性，并提供了安装和使用方法。 在VS Code中使用Snippet Craft扩展提高编码效率 https://blog.matoapp.net/posts/10673802/ 2024-08-23T00:18:00.000Z 2025-09-24T16:30:02.666Z Snippet Craft

一个VS Code代码片段管理插件

功能

创建和插入代码片段

在编辑器区域右键菜单中点击插入Snippet，或在代码片段视图中点击条目，则会将代码片段插入到当前激活文档的光标位置。

代码片段编辑

代码片段在左侧栏中，根据创建时的文件内容类型，分组显示代码片段，可编辑已有的代码片段。

代码片段预览

鼠标移动到代码片段条目上时，显示tooltip预览

默认映射

映射是插入代码片段时，自动替换的变量。

代码片段中通过设置占位符${VAR_NAME}，在插入代码片段时，将自动替换为全局变量中的值。可用的映射如下表：

类别变量描述
文件和编辑器相关TM_SELECTED_TEXT当前选定的文本或空字符串
TM_CURRENT_LINE当前行的内容
TM_CURRENT_WORD光标下的单词或空字符串的内容
TM_LINE_INDEX基于零索引的行号
TM_LINE_NUMBER基于一个索引的行号
TM_FILENAME当前文档的文件名
TM_FILENAME_BASE当前文档的文件名（不含扩展名）
TM_DIRECTORY当前文档的目录
TM_FILEPATH当前文档的完整文件路径
RELATIVE_FILEPATH当前文档的相对文件路径（相对于打开的工作区或文件夹）
CLIPBOARD剪贴板的内容
WORKSPACE_NAME打开的工作区或文件夹的名称
WORKSPACE_FOLDER打开的工作区或文件夹的路径
CURSOR_INDEX基于零索引的游标编号
CURSOR_NUMBER基于单索引的游标编号
时间相关CURRENT_YEAR本年度
CURRENT_YEAR_SHORT当年的最后两位数字
CURRENT_MONTH两位数字的月份（例如“02”）
CURRENT_MONTH_NAME月份的全名（例如“July”）
CURRENT_MONTH_NAME_SHORT月份的简短名称（例如“Jul”）
CURRENT_DATE以两位数字表示的月份中的某一天（例如“08”）
CURRENT_DAY_NAME日期的名称（例如“星期一”）
CURRENT_DAY_NAME_SHORT当天的简短名称（例如“Mon”）
CURRENT_HOUR24小时制格式的当前小时
CURRENT_MINUTE两位数的当前分钟数
CURRENT_SECOND当前秒数为两位数
CURRENT_SECONDS_UNIX自 Unix 纪元以来的秒数
CURRENT_TIMEZONE_OFFSET当前 UTC 时区偏移量为 +HH
或者 -HH
(例如“-07:00”)
其他RANDOM66 个随机 Base-10 数字
RANDOM_HEX66 个随机 Base-16 数字
UUID第四版UUID

注意：当自定义映射值未设置或者不可用时，将直接显示变量占位符

自定义映射

扩展初始化时，插入了三个常用的自定义映射，你可以自由更改或添加自定义映射。

示例：

代码片段内容

1
2
3
4
value of 'AUTHOR' is: ${AUTHOR}
value of 'COMPANY' is: ${COMPANY}
value of 'MAIL' is: ${MAIL}
value of 'FOOBAR' (non-exist) is: ${FOOBAR}

插入代码片段后，显示如下：

1
2
3
4
value of 'AUTHOR' is: 林晓lx
value of 'COMPANY' is: my-company
value of 'MAIL' is: jevonsflash@qq.com
value of 'FOOBAR' (non-exist) is: ${FOOBAR}

与自定义映射一样，当默认映射值未设置或者不可用时，将直接显示变量占位符

自动完成

代码片段可在编辑器中显示自动提示和补全内容。

快速开始

通过点击上方横幅上的安装按钮安装 Snippet Craft，或在 VS Code 的扩展侧边栏中搜索 Snippet Craft 进行安装。

更新内容

DateVersionContent
V0.1.02024-8-22初始版本

Todo

  • 支持更多语言
  • 使用monaco-editor
  • 导入导出功能

作者信息

作者：林小

邮箱：jevonsflash@qq.com

License

The MIT License (MIT)

项目地址

Github:snippet-craft

]]> 扩展初始化时，插入了三个常用的自定义映射，你可以自由更改或添加自定义映射。示例：代码片段内容value of 'AUTHOR' is: 林晓lx与自定义映射一样，当默认映射值未设置或者不可用时，将直接显示变量占位符。 [学习笔记]在不同项目中切换Node.js版本 https://blog.matoapp.net/posts/4ba5d0e5/ 2024-08-22T19:53:00.000Z 2025-09-24T16:30:02.654Z

在开发中，可能会遇到不同的Vue项目需要不同的Node.js，在开发机上如何快速切换Node的版本呢？

使用 Node Version Manager (NVM)

安装 NVM

在 Linux 或 macOS 上可以通过以下命令安装 NVM：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

在 Windows 上，可以下载并安装 nvm-windows。

使用 NVM 安装和切换 Node.js 版本

安装一个特定版本的 Node.js：

1
2
3
nvm install 16

nvm install 22

切换到指定的 Node.js 版本：

nvm use 22

可以通过以下命令检查当前使用的 Node.js 版本：

node -v

为项目指定 Node.js 版本

可以在项目根目录中创建一个 .nvmrc 文件，里面指定该项目需要使用的 Node.js 版本：

16

然后，在进入项目目录时，运行以下命令自动使用 .nvmrc 中指定的版本：

nvm use

使用环境变量指定 Node.js

安装多个版本的 Node.js

下载 Node.js，并在不同目录下安装多个版本。如C:\Program Files\nodejs16和C:\Program Files\nodejs22

设置环境变量

可以在系统的环境变量配置中手动设置 NODE_HOME。

在 Windows 上：

  1. 打开 “系统属性” > “高级系统设置” > “环境变量”。
  2. 在 “系统变量” 或 “用户变量” 中点击 “新建”。
  3. 创建一个新的变量 NODE_HOME，并设置它的值为 Node.js 安装路径。

  1. 找到 Path 变量，点击 “编辑”。
  2. 添加一个新条目：%NODE_HOME%。

在 macOS/Linux 上：

  1. 打开终端，编辑 .bashrc、.bash_profile 或 .zshrc 文件：

    export NODE_HOME=/usr/bin/nodejs22 export PATH=$NODE_HOME:$PATH

  2. 保存文件并运行 source ~/.bashrc 或 source ~/.zshrc 以使更改生效。

通过更改 NODE_HOME 环境变量的路径，实现切换Node.js 的版本。

验证配置

可以通过以下命令验证 Node.js 是否已成功通过 NODE_HOME 变量加载：

node -v

输出应显示所配置的 Node.js 版本：

cross-env 是一个用于在不同操作系统上设置和使用环境变量的工具，可以用它来切换 NODE_HOME 环境变量，以确保在不同的操作系统上都能正确设置和使用 Node.js 的路径。

在 package.json 中，可以定义如下的 npm 脚本：

1
2
3
4
5
6
7
8
{
  "scripts": {
    "set-node16": "cross-env NODE_HOME=C:\\Program Files\\nodejs16",
    "set-node22": "cross-env NODE_HOME=C:\\Program Files\\nodejs22",
    "set-node16-unix": "cross-env NODE_HOME=/usr/bin/nodejs16",
    "set-node22-unix": "cross-env NODE_HOME=/usr/bin/nodejs22"
  }
}

使用 npm 脚本切换

可以根据操作系统和需要的 Node.js 版本运行相应的脚本：

在 Windows 上：

npm run set-node16

在 Unix 系统上（Linux/Mac）：

npm run set-node16-unix

总结：最好是通过第一种方式，因为手动配置环境变量的方式会产生依赖，需要在同事的电脑上手动配置。

]]> 在开发中，可能会遇到不同的Vue项目需要不同的Node.js，在开发机上如何快速切换Node的版本呢？总结：最好是通过第一种方式，因为手动配置环境变量的方式会产生依赖，需要在同事的电脑上手动配置。cross-env 是一个用于在不同操作系统上设置和使用环境变量的工具，可以用它来切换。环境变量，以确保在不同的操作系统上都能正确设置和使用 Node.js 的路径。下载 Node.js，并在不同目录下安装多个版本。环境变量的路径，实现切换Node.js 的版本。可以在系统的环境变量配置中手动设置。 [VS Code扩展]写一个代码片段管理插件（二）：功能实现 https://blog.matoapp.net/posts/9244fcab/ 2024-08-22T09:51:00.000Z 2025-09-24T16:30:02.618Z

创建和插入代码片段

VS Code扩展提供了数据存储，其中globalState是使用全局存储的Key-Value方式来保存用户状态，支持在不同计算机上保留某些用户状态，详情请参考官方文档

若在编辑器区域有选中的文本，点击右键菜单中点击创建Snippet，则调用extension.snippetCraft.createSnipp命令，执行创建代码片段。

创建服务类 SnippService.ts，代码如下

1
2
3
4
5
export async function AddSnipp(context: ExtensionContext, state: Partial<ISnipp>) {
  const content = await getSnippText();
  const trimmedName = content?.text?.trim().substring(0, 20) || '';
  await _addOrUpdateSnipp(context, { ...state, name: trimmedName }, content)
}

在_addOrUpdateSnipp方法中对snipps进行更新操作

1
2
3
4
5
6
7
async function _addOrUpdateSnipp(context: ExtensionContext, state: Partial<ISnipp>, content?: {
  text: string | undefined;
  type: string | undefined;
}, snippIndex?: number) {
   
  ...
  context.globalState.update("snipps", updatedSnipps);

若在编辑器区域右键菜单中点击插入Snippet，或在代码片段视图中点击条目，则调用extension.snippetCraft.insertSnipps命令，它会调用InsertSnipp方法执行插入代码片段操作。

在服务类 SnippService.ts，插入如下代码

1
2
3
4
5
6
7
8
9
10
export async function InsertSnipp(context: ExtensionContext, snipp: ISnipp) {
  const editor = window.activeTextEditor;
  if (editor && SnippDataProvider.isSnipp(snipp)) {
    const position = editor?.selection.active;
    editor.edit(async (edit) => {

      edit.insert(position, snipp.content || '');
    });
  } 
}

代码片段列表

代码片段显示为一个树形结构，根据创建时的文件内容类型，分组显示代码片段条目

创建代码片段和分组条目的接口类型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import * as vscode from "vscode";

export interface ISnipp {
  name: string;
  content: string;
  contentType: string;
  created: Date;
  lastUsed: Date;
}

export interface IGroup {
  name: string;
  contentType: string | undefined;
}

在SnippItem中创建获取所有分组类型的get访问器，和获取分组下的条目getChildren方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

export class SnippItem {
  constructor(
    readonly view: string,
    private context: vscode.ExtensionContext
  ) { }

  public get roots(): Thenable<IGroup[]> {
    const snipps = this.context?.globalState?.get("snipps", []);
    const types = snipps
      .map((snipp: ISnipp) => snipp.contentType)
      .filter((value, index, self) => self.indexOf(value) === index)
      .map((type) => ({ name: type, contentType: undefined }));
    return Promise.resolve(types);
  }

  public getChildren(node: IGroup): Thenable<ISnipp[]> {
    const snipps = this.context?.globalState
      ?.get("snipps", [])
      .filter((snipp: ISnipp) => {
        return snipp.contentType === node.name;
      })
      .sort((a: ISnipp, b: ISnipp) => a.name.localeCompare(b.name));

    return Promise.resolve(snipps);
  }


1
2
3

export class GroupItem { }

VS Code扩展的侧边栏中显示内容需为树形结构，通过实现TreeDataProvider为内容提供数据，请参考官方说明

实现getChildren方法

1
2
3
4
5
6
7
8
9
10
11
12
13
export class SnippDataProvider
  implements
    vscode.TreeDataProvider<ISnipp | IGroup>
{
  
  public getChildren(
    element?: ISnipp | IGroup
  ): ISnipp[] | Thenable<ISnipp[]> | IGroup[] | Thenable<IGroup[]> {
    return element ? this.model.getChildren(element) : this.model.roots;
  }

}

代码片段预览

实现getTreeItem方法，显示预览

点击时调用extension.snippetCraft.insertEntry命令实现插入代码片段，command部分在上一章节有介绍。

鼠标移动到代码片段条目上时，显示tooltip预览

代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public getTreeItem(element: ISnipp | IGroup): vscode.TreeItem {
    const t = element.name;
    const isSnip = SnippDataProvider.isSnipp(element);
    const snippcomm = {
      command: "extension.snippetCraft.insertEntry",
      title: '',
      arguments: [element],
    };

    let snippetInfo: string = `[${element.contentType}] ${element.name}`;

    return {
      // @ts-ignore
      label: isSnip ? element.name : element.name,
      command: isSnip ? snippcomm : undefined,
      iconPath:isSnip ? new ThemeIcon("code"):new ThemeIcon("folder"),
      tooltip: isSnip
        ? new vscode.MarkdownString(
            // @ts-ignore
            `**标题：**${snippetInfo}\n\n**修改时间：**${element.created}\n\n**最近使用：**${element.lastUsed}\n\n**预览：**\n\`\`\`${element.contentType}\n${element.content}\n\`\`\``
          )
        : undefined,
      collapsibleState: !isSnip
        ? vscode.TreeItemCollapsibleState.Collapsed
        : undefined,
    };
  }

代码片段编辑

编辑器是一个输入框，由于VS Code的输入框不支持多行输入，所以需要使用webview实现多行输入。同时需要提交按钮与取消按钮

首先创建一个多行文本框的WebView，
在服务类 SnippService.ts，创建一个函数getWebviewContent，返回一个HTML字符串，用于创建一个多行输入框。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
function getWebviewContent(placeholder: string, initialValue: string): string {
  return `
      <!DOCTYPE html>
      <html lang="en">
      <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Multiline Input</title>
      </head>
      <body>
        <textarea id="inputBox" rows="10" cols="50" placeholder="${placeholder}">${initialValue}</textarea>
        <br>
        <button onclick="submitText()">提交</button>
        <button onclick="cancel()">取消</button>
        <script>
          const vscode = acquireVsCodeApi();
          function submitText() {
            const text = document.getElementById('inputBox').value;
            vscode.postMessage({ command: 'submit', text: text });
          }
          function cancel() {
            vscode.postMessage({ command: 'cancel' });
          }
        </script>
      </body>
      </html>
    `;
}

添加处理函数，当用户点击“提交“时，将文本输入框中的内容返回，同时关闭输入框窗口。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

async function showInputBoxWithMultiline(context: ExtensionContext, placeholder: string, initialValue: string): Promise<string | undefined> {
  const panel = window.createWebviewPanel(
    'multilineInput',
    'Multiline Input',
    ViewColumn.One,
    {
      enableScripts: true
    }
  );

  panel.webview.html = getWebviewContent(placeholder, initialValue);

  return new Promise<string | undefined>((resolve) => {
    panel.webview.onDidReceiveMessage(
      message => {
        switch (message.command) {
          case 'submit':
            resolve(message.text);
            panel.dispose();
            return;
          case 'cancel':
            resolve(undefined);
            panel.dispose();
            return;
        }
      },
      undefined,
      context.subscriptions
    );
  });
}

在添加代码片段和编辑代码片段时触发函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

export async function AddSnippFromEditor(context: ExtensionContext, state: Partial<ISnipp>) {
  const content = await showInputBoxWithMultiline(context, '请输入Snippet内容', '');
  if (content) {
    _addOrUpdateSnipp(context, state, { text: content, type: "TEXT" })

  }
}

export async function EditSnipp(context: ExtensionContext, state: Partial<ISnipp>, snippIndex: number) {
  const content = await showInputBoxWithMultiline(context, '请输入Snippet内容', state.content ?? '');
  if (content) {
    _addOrUpdateSnipp(context, state, { text: content, type: state.contentType ?? "TEXT" }, snippIndex)

  }
}

自定义映射

映射是插入代码片段时，自动替换的变量，他们通过Key-Value形式存储于globalState中。

代码片段中通过设置占位符（如${AUTHOR}），在插入代码片段时，将自动替换为全局变量中的值。

当自定义映射值未设置或者不可用时，将直接显示变量占位符

扩展初始化时，插入了三个常用的自定义映射，你可以自由更改或添加自定义映射。

  • ${AUTHOR}: 作者姓名
  • ${COMPANY}: 公司名称
  • ${MAIL}: 邮箱地址

扩展中所有的自定义映射，呈现于“映射表”树视图中。

示例：

代码片段内容

1
2
3
4
value of 'AUTHOR' is: ${AUTHOR}
value of 'COMPANY' is: ${COMPANY}
value of 'MAIL' is: ${MAIL}
value of 'FOOBAR' (non-exist) is: ${FOOBAR}

插入代码片段后，显示如下：

1
2
3
4
value of 'AUTHOR' is: 林晓lx
value of 'COMPANY' is: my-company
value of 'MAIL' is: jevonsflash@qq.com
value of 'FOOBAR' (non-exist) is: ${FOOBAR}

首先定义KVItem类：

1
2
3
4
5
6
7
8
9
10
11
export class KVItem extends vscode.TreeItem {
    constructor(
      public readonly key: string,
      public readonly value: string | undefined
    ) {
      super(key, vscode.TreeItemCollapsibleState.None);
      this.tooltip = `${this.key}: ${this.value}`;
      this.description = this.value;
      this.contextValue = 'kvItem';
    }
  }

“映射表”树视图中显示内容需为树形结构，同样需要定义KVTreeDataProvider，在此实现刷新、添加、删除、获取子节点等方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
export class KVTreeDataProvider implements vscode.TreeDataProvider<KVItem> {
  private _onDidChangeTreeData: vscode.EventEmitter<KVItem | undefined> = new vscode.EventEmitter<KVItem | undefined>();
  readonly onDidChangeTreeData: vscode.Event<KVItem | undefined> = this._onDidChangeTreeData.event;

  constructor(private globalState: vscode.Memento) {}

  getTreeItem(element: KVItem): vscode.TreeItem {
    return element;
  }

  getChildren(element?: KVItem): Thenable<KVItem[]> {
    if (element) {
      return Promise.resolve([]);
    } else {
      const kvObject = this.globalState.get<{ [key: string]: string }>('key-value', {});
      const keys = Object.keys(kvObject);
      return Promise.resolve(keys.map(key => new KVItem(key, kvObject[key])));
    }
  }

  refresh(): void {
    this._onDidChangeTreeData.fire(undefined);
  }

  addOrUpdateKey(key: string, value: string): void {
    const kvObject = this.globalState.get<{ [key: string]: string }>('key-value', {});
    kvObject[key] = value;
    this.globalState.update('key-value', kvObject);
    this.refresh();
  }

  deleteKey(key: string): void {
    const kvObject = this.globalState.get<{ [key: string]: string }>('key-value', {});
    delete kvObject[key];
    this.globalState.update('key-value', kvObject);
    this.refresh();
  }
}

默认映射

默认映射是扩展内置的映射功能，可用的映射如下

文件和编辑器相关：

  • TM_SELECTED_TEXT: 当前选定的文本或空字符串
  • TM_CURRENT_LINE: 当前行的内容
  • TM_CURRENT_WORD: 光标下的单词或空字符串的内容
  • TM_LINE_INDEX: 基于零索引的行号
  • TM_LINE_NUMBER: 基于一个索引的行号
  • TM_FILENAME: 当前文档的文件名
  • TM_FILENAME_BASE: 当前文档的文件名（不含扩展名）
  • TM_DIRECTORY: 当前文档的目录
  • TM_FILEPATH: 当前文档的完整文件路径
  • RELATIVE_FILEPATH: 当前文档的相对文件路径（相对于打开的工作区或文件夹）
  • CLIPBOARD: 剪贴板的内容
  • WORKSPACE_NAME: 打开的工作区或文件夹的名称
  • WORKSPACE_FOLDER: 打开的工作区或文件夹的路径
  • CURSOR_INDEX: 基于零索引的游标编号
  • CURSOR_NUMBER: 基于单索引的游标编号

时间相关：

  • CURRENT_YEAR: 本年度
  • CURRENT_YEAR_SHORT: 当年的最后两位数字
  • CURRENT_MONTH: 两位数字的月份（例如“02”）
  • CURRENT_MONTH_NAME: 月份的全名（例如“July”）
  • CURRENT_MONTH_NAME_SHORT: 月份的简短名称（例如“Jul”）
  • CURRENT_DATE: 以两位数字表示的月份中的某一天（例如“08”）
  • CURRENT_DAY_NAME: 日期的名称（例如“星期一”）
  • CURRENT_DAY_NAME_SHORT: 当天的简短名称（例如“Mon”）
  • CURRENT_HOUR24: 小时制格式的当前小时
  • CURRENT_MINUTE: 两位数的当前分钟数
  • CURRENT_SECOND: 当前秒数为两位数
  • CURRENT_SECONDS_UNIX: 自 Unix 纪元以来的秒数
  • CURRENT_TIMEZONE_OFFSET当前 UTC 时区偏移量为 +HH:MM 或者 -HH:MM (例如“-07:00”)。

其他：

  • RANDOM6: 个随机 Base-10 数字
  • RANDOM_HEX6: 个随机 Base-16 数字
  • UUID: 第四版UUID

这些项目参考至VS Code 代码片段变量，请查看VSCode官方文档

与自定义映射一样，当默认映射值未设置或者不可用时，将直接显示变量占位符

实现方法如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

export async function ReplacePlaceholders(text: string, context: ExtensionContext): Promise<string> {
  const editor = window.activeTextEditor;
  const clipboard = await env.clipboard.readText();
  const workspaceFolders = workspace.workspaceFolders;
  const currentDate = new Date();
  const kvObject = context.globalState.get<{ [key: string]: string }>('key-value', {});

  const replacements: { [key: string]: string } = {
    '${TM_SELECTED_TEXT}': editor?.document.getText(editor.selection) || '',
    '${TM_CURRENT_LINE}': editor?.document.lineAt(editor.selection.active.line).text || '',
    '${TM_CURRENT_WORD}': editor?.document.getText(editor.document.getWordRangeAtPosition(editor.selection.active)) || '',
    '${TM_LINE_INDEX}': (editor?.selection.active.line ?? 0).toString(),
    '${TM_LINE_NUMBER}': ((editor?.selection.active.line ?? 0) + 1).toString(),
    '${TM_FILENAME}': editor ? path.basename(editor.document.fileName) : '',
    '${TM_FILENAME_BASE}': editor ? path.basename(editor.document.fileName, path.extname(editor.document.fileName)) : '',
    '${TM_DIRECTORY}': editor ? path.dirname(editor.document.fileName) : '',
    '${TM_FILEPATH}': editor?.document.fileName || '',
    '${RELATIVE_FILEPATH}': editor && workspaceFolders ? path.relative(workspaceFolders[0].uri.fsPath, editor.document.fileName) : '',
    '${CLIPBOARD}': clipboard,
    '${WORKSPACE_NAME}': workspaceFolders ? workspaceFolders[0].name : '',
    '${WORKSPACE_FOLDER}': workspaceFolders ? workspaceFolders[0].uri.fsPath : '',
    '${CURSOR_INDEX}': (editor?.selections.indexOf(editor.selection) ?? 0).toString(),
    '${CURSOR_NUMBER}': ((editor?.selections.indexOf(editor.selection) ?? 0) + 1).toString(),
    '${CURRENT_YEAR}': currentDate.getFullYear().toString(),
    '${CURRENT_YEAR_SHORT}': currentDate.getFullYear().toString().slice(-2),
    '${CURRENT_MONTH}': (currentDate.getMonth() + 1).toString().padStart(2, '0'),
    '${CURRENT_MONTH_NAME}': currentDate.toLocaleString('default', { month: 'long' }),
    '${CURRENT_MONTH_NAME_SHORT}': currentDate.toLocaleString('default', { month: 'short' }),
    '${CURRENT_DATE}': currentDate.getDate().toString().padStart(2, '0'),
    '${CURRENT_DAY_NAME}': currentDate.toLocaleString('default', { weekday: 'long' }),
    '${CURRENT_DAY_NAME_SHORT}': currentDate.toLocaleString('default', { weekday: 'short' }),
    '${CURRENT_HOUR}': currentDate.getHours().toString().padStart(2, '0'),
    '${CURRENT_MINUTE}': currentDate.getMinutes().toString().padStart(2, '0'),
    '${CURRENT_SECOND}': currentDate.getSeconds().toString().padStart(2, '0'),
    '${CURRENT_SECONDS_UNIX}': Math.floor(currentDate.getTime() / 1000).toString(),
    '${CURRENT_TIMEZONE_OFFSET}': formatTimezoneOffset(currentDate.getTimezoneOffset()),
    '${RANDOM}': Math.random().toString().slice(2, 8),
    '${RANDOM_HEX}': Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0'),
    '${UUID}': generateUUID()
  };

  Object.keys(kvObject).forEach(key => {
    replacements[`$\{${key}\}`] = kvObject[key];
  });

  return text.replace(/\$\{(\w+)\}/g, (match, key) => {
    return replacements[match] || match;
  });
}

自动完成

自动完成是VS Code编辑器提供的一个功能，用于在编辑器中显示自动提示和补全内容。扩展提供了基于代码片段的自动完成功能。

CompletionItemProvider用于注册自动完成的规则，提供者约定了在指定的文档类型下，当输入的字符匹配时，将出现自动完成上下文菜单。

上下文菜单中列出所有可用的自动完成条目，每个条目由CompletionItem定义，点击对应条目后，将处理后的字符串返回，填写到编辑器当前光标处。

languages.registerCompletionItemProvider用于注册自动完成的规则提供者。

在extension.ts中注册初始化时，所有的自动完成条目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
const providers = contentTypes
  .filter((value, index, self) => self.indexOf(value) === index)
  .map(type =>
    languages.registerCompletionItemProvider(type, {
      provideCompletionItems(
        document: TextDocument,
        position: Position,
        token: CancellationToken,
        context: CompletionContext
      ) {
        return new Promise<CompletionItem[]>((resolve, reject) => {

          var result = snipps
            .filter((snipp: ISnipp) => {
              return snipp.contentType === type;
            })
            .map(async (snipp: ISnipp) => {
              const replacedContentText = await ReplacePlaceholders(snipp.content, extensionContext);

              const commandCompletion = new CompletionItem(snipp.name);
              commandCompletion.insertText = replacedContentText || '';
              return commandCompletion;
            });

          Promise.all(result).then(resolve);
        });
      }
    })
  );

context.subscriptions.push(...providers);

SnippService.ts_addOrUpdateSnipp方法中配置修改或新增的自动完成条目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

if (content?.type && state.name) {
  languages.registerCompletionItemProvider(content.type, {
    provideCompletionItems(
      document: TextDocument,
      position: Position,
      token: CancellationToken,
      context: CompletionContext
    ) {
      return new Promise<CompletionItem[]>((resolve, reject) => {
        ReplacePlaceholders(state.content || '', extensionContext).then(res => {
          const replacedContentText = res;
          const commandCompletion = new CompletionItem(state.name || '');
          commandCompletion.insertText = replacedContentText || '';
          resolve([commandCompletion]);
        });


      });
    }
  });
}

项目地址

Github:snippet-craft

]]> 映射是插入代码片段时，自动替换的变量，他们通过Key-Value形式存储于globalState中。代码片段中通过设置占位符（如${AUTHOR}），在插入代码片段时，将自动替换为全局变量中的值。当自定义映射值未设置或者不可用时，将直接显示变量占位符扩展初始化时，插入了三个常用的自定义映射，你可以自由更改或添加自定义映射。${AUTHOR}: 作者姓名${COMPANY}: 公司名称${MAIL}: 邮箱地址扩展中所有的自定义映射，呈现于“映射表”树视图中。示例：代码片段内容。 [VS Code扩展]写一个代码片段管理插件（一）：介绍与界面搭建 https://blog.matoapp.net/posts/948f6f1b/ 2024-08-02T23:20:00.000Z 2025-09-24T16:30:02.606Z

写代码的时候，经常要输入重复的内容，虽然VS Code提供了代码片段功能，但是创建自定义代码片段时，需要写JSON格式的配置，这些JSON文件在用户文件夹下，没有统一的界面管理，而且对于我来说，制表符补全这样的高级功能并不是必需的。

变量映射可以通过内置的映射规则在插入片段时自动生成这些内容。VS Code自带的功能比较单一，我需要一个自定义的变量映射功能，可以自定义Key-Value做为可灵活配置的变量映射。

VS Code提供了一组API，用于自定义或增强软件功能，称之为VS Code插件（或扩展）。

我基于上述的考虑，写一个带有变量映射功能代码片段管理VS Code扩展：SnippetCraft。

VS Code扩展机制

首先需要大致了解VS Code的扩展机制，VS Code可以看成一个框架，可以想象是你车上的仪表台，比如时速表仪表台，中控大屏，灯光、空调控制等独立面板所在的占位。

VS Code这些框架的部分，官方称之为“容器”，整个VS Code由6个容器组成，分别是：活动栏，主边栏，编辑器，辅边栏，面板，状态栏。

每个容器中，包含扩展提供的按钮，或者视图的区域。类似仪表台控制上的控制面板，比如灯光面板上有灯的开关，有些是预留的槽位。通过增加改装件使用这些预留槽位。

这些区域，官方称之为“项目”。常用的项目有侧边栏，编辑器，状态栏，面板上的工具栏区域。扩展可以将项目添加到各种容器中。

此外，VS Code扩展还提供常用的功能，比如数据持久化，文件选择器，输入框，通知弹窗，网页视图等。

VS Code扩展是一个基础功能，通过扩展可以满足软件的所有功能增强，包括内置的核心功能，如文件管理，搜索，Git，调试器，这些都是通过扩展实现的。

VS Code为了体验一致性，禁用扩展中UI元素自定义样式。

项目搭建

请确保已安装 Node.js。使用 Yeoman 和 VS Code 扩展生成器来快速创建扩展项目。首先安装 Yeoman 和生成器：

1
2
npm install -g yo generator-code
yo code

项目会自动创建一个HelloWorld扩展。

如果手动创建项目，可以参考下面的目录结构

1
2
3
4
5
6
7
8
9
10
my-VS Code-extension/
├── .VS Code/
│   └── extensions.json
├── src/
│   └── extension.ts
├── .gitignore
├── package.json
├── tsconfig.json
├── README.md

准备图标，扩展需要一个产品展示图标。图标为128x128像素的PNG格式文件
准备活动栏按钮图标，图标为24x24像素，居中于50x40像素的块内，填充颜色为’rgb(215, 218, 224)’或’#d7dae0’。建议使用SVG格式的图标。

VS Code扩展在package.json中声明“贡献点”，“贡献点”用于描述该扩展可以为VS Code增强哪些功能，请参考官方说明

在package.json文件的contributes节点中，我们添加扩展用到的所有命令：

Command操作
extension.snippetCraft.searchSnipps代码片段搜索
extension.snippetCraft.insertSnipps插入代码片段
extension.snippetCraft.deleteAllSnippets删除全部代码片段
extension.snippetCraft.createSnipp创建代码片段
extension.snippetCraft.refreshEntry刷新代码片段列表
extension.snippetCraft.addEntry添加代码片段
extension.snippetCraft.editEntry编辑代码片段
extension.snippetCraft.editTitle编辑代码片段标题
extension.snippetCraft.deleteEntry删除代码片段
extension.snippetCraft.insertEntry插入代码片段
extension.snippetCraft.addKv添加映射
extension.snippetCraft.refreshKv刷新映射列表
extension.snippetCraft.deleteKv删除映射
extension.snippetCraft.editKv编辑映射

创建UI元素

活动栏按钮

点击此按钮将打开VS Code扩展的主边栏视图。图标和名称一般为产品的Logo和名称

在package.json文件的contributes节点中，添加如下内容：

1
2
3
4
5
6
7
8
9
"viewsContainers": {
      "activitybar": [
        {
          "id": "snippsView",
          "title": "Snippet Craft",
          "icon": "./logo.svg"
        }
      ]
    }

完成活动栏按钮的添加

主边栏视图

主边栏中用于直观地列出代码片段的列表和映射表

在package.json文件的contributes节点中，添加如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
"views": {
    "snippsView": [
    {
        "id": "view.snippetCraft.snippsView",
        "name": "Snippets列表"
    },
    {
        "id": "view.snippetCraft.dictionaryView",
        "name": "映射表"
    }
    ]
},

完成主边栏视图的添加

主边栏工具栏按钮

在package.json文件的contributes节点中，添加如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
"view/title": [
    {
        "command": "extension.snippetCraft.addEntry",
        "group": "navigation",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.refreshEntry",
        "group": "navigation",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.searchSnipps",
        "group": "navigation",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.addKv",
        "when": "view == view.snippetCraft.dictionaryView",
        "group": "navigation"
    },
    {
        "command": "extension.snippetCraft.refreshKv",
        "when": "view == view.snippetCraft.dictionaryView",
        "group": "navigation"
    }
    
    ]
},

完成主边栏工具栏按钮的添加


侧边栏右键菜单

在package.json文件的contributes节点中，添加如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

"view/item/context": [
    {
        "command": "extension.snippetCraft.editTitle",
        "group": "snippet",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.deleteEntry",
        "group": "snippet",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.insertEntry",
        "group": "snippet",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.editEntry",
        "group": "snippet",
        "when": "view == view.snippetCraft.snippsView"
    },
    {
        "command": "extension.snippetCraft.editKv",
        "when": "view == view.snippetCraft.dictionaryView",
        "group": "kveditor"
    },
    {
        "command": "extension.snippetCraft.deleteKv",
        "when": "view == view.snippetCraft.dictionaryView",
        "group": "kveditor"
    }
    ],

完成侧边栏右键菜单的添加

编辑器右键菜单

在编辑器区域右键弹出的上下文菜单中选择“插入Snippet”，可以选择一个已有的片段插入当前光标所在位置

当编辑器中有文本被选中时，上下文菜单的“创建Snippet”会显示，点击时选中的文本将作为代码片段被存储。

1
2
3
4
5
6
7
8
9
10
11
12
"menus": {
    "editor/context": [
    {
        "command": "extension.snippetCraft.createSnipp",
        "when": "editorHasSelection",
        "group": "snippet"
    },
    {
        "command": "extension.snippetCraft.insertSnipps",
        "group": "snippet"
    }
    ],

完成编辑器右键菜单的添加

项目地址

Github:snippet-craft

]]> 功能，但是创建自定义代码片段时，需要写JSON格式的配置，这些JSON文件在用户文件夹下，没有统一的界面管理，而且对于我来说，制表符补全这样的高级功能并不是必需的。VS Code扩展是一个基础功能，通过扩展可以满足软件的所有功能增强，包括内置的核心功能，如文件管理，搜索，Git，调试器，这些都是通过扩展实现的。VS Code这些框架的部分，官方称之为“容器”，整个VS Code由6个容器组成，分别是：活动栏，主边栏，编辑器，辅边栏，面板，状态栏。常用的项目有侧边栏，编辑器，状态栏，面板上的工具栏区域。 [MAUI 项目实战] 笔记App（二）：数据库设计 https://blog.matoapp.net/posts/3b234df5/ 2024-07-19T10:52:00.000Z 2025-09-24T16:30:02.414Z

Sqlite配置

应用程序里使用Sqlite作为数据库，使用EntityFramworkCore作为ORM，使用CodeFirst方式用EFCore初始化Sqlite数据库文件：mato.db

在MatoProductivity.Core项目的appsettings.json中添加本地sqlite连接字符串

1
2
3
4
"ConnectionStrings": {
  "Default": "Data Source=file:{0};"
},
...

这里文件是一个占位符，通过代码hardcode到配置文件

在MatoProductivityCoreModule.cs中，重写PreInitialize并设置Configuration.DefaultNameOrConnectionString：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public override void PreInitialize()
{
    LocalizationConfigurer.Configure(Configuration.Localization);

    Configuration.Settings.Providers.Add<CommonSettingProvider>();

    string documentsPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), MatoProductivityConsts.LocalizationSourceName);

    var configuration = AppConfigurations.Get(documentsPath, development);
    var connectionString = configuration.GetConnectionString(MatoProductivityConsts.ConnectionStringName);

    var dbName = "mato.db";
    string dbPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), MatoProductivityConsts.LocalizationSourceName, dbName);

    Configuration.DefaultNameOrConnectionString = String.Format(connectionString, dbPath);
    base.PreInitialize();
}

创建实体

接下来定义实体类

笔记实体类

笔记用于存储实体，在笔记列表中，每个笔记都有标题和内容，创建时间等内容。

定义于\MatoProductivity.Core\Models\Entities\Note.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

public class Note : FullAuditedEntity<long>
{
    public Note()
    {

    }
    public Note(string name, bool isHidden, bool isRemovable)
    {
        Title = name;
        IsHidden = isHidden;
        IsRemovable = isRemovable;
    }


    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    public ICollection<NoteSegment> NoteSegments { get; set; }

    public string Title { get; set; }
    public string Type { get; set; }
    public string Status { get; set; }
    public string Desc { get; set; }
    public string Icon { get; set; }
    public string Color { get; set; }
    public string BackgroundColor { get; set; }
    public string BackgroundImage { get; set; }

    public string PreViewContent { get; set; }

    public bool IsEditable { get; set; }

    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }
    public bool CanSimplified { get; set; }

}


笔记分组实体

定义于\MatoProductivity.Core\Models\Entities\NoteGroup.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public class NoteGroup : FullAuditedEntity<long>
{
    public NoteGroup()
    {

    }
    public NoteGroup(string name, bool isHidden, bool isRemovable)
    {
        Title = name;
        IsHidden = isHidden;
        IsRemovable = isRemovable;
    }

    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }
    public string Title { get; set; }

    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }

    public ICollection<Note> Notes { get; set; }
}

笔记片段实体

定义于\MatoProductivity.Core\Models\Entities\NoteSegment.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
public class NoteSegment : FullAuditedEntity<long>, INoteSegment
{
    public NoteSegment()
    {

    }



    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    [ForeignKey(nameof(NoteId))]
    public Note Note { get; set; }

    public ICollection<NoteSegmentPayload> NoteSegmentPayloads { get; set; }

    public long NoteId { get; set; }

    public string Title { get; set; }
    public string Type { get; set; }
    public string Status { get; set; }
    public string Desc { get; set; }
    public string Icon { get; set; }
    public string Color { get; set; }
    public int Rank { get; set; }

    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }


    public INoteSegmentPayload GetNoteSegmentPayload(string key)
    {
        if (NoteSegmentPayloads != null)
        {
            return NoteSegmentPayloads.FirstOrDefault(c => c.Key == key);
        }
        return default;
    }




    public void SetNoteSegmentPayload(INoteSegmentPayload noteSegmentPayload)
    {
        if (NoteSegmentPayloads != null)
        {
            var currentPayload = NoteSegmentPayloads.FirstOrDefault(c => c.Key == noteSegmentPayload.Key);
            if (currentPayload != null)
            {
                NoteSegmentPayloads.Remove(currentPayload);
            }
            if (!this.IsTransient())
            {
                (noteSegmentPayload as NoteSegmentPayload).NoteSegmentId = this.Id;
            }
            NoteSegmentPayloads.Add((noteSegmentPayload as NoteSegmentPayload));
        }
    }

    public INoteSegmentPayload GetOrSetNoteSegmentPayload(string key, INoteSegmentPayload noteSegmentPayload)
    {
        if (NoteSegmentPayloads != null)
        {
            var currentPayload = NoteSegmentPayloads.FirstOrDefault(c => c.Key == key);
            if (currentPayload != null)
            {
                return currentPayload;
            }
            if (noteSegmentPayload != null)
            {
                if (!this.IsTransient())
                {
                    (noteSegmentPayload as NoteSegmentPayload).NoteSegmentId = this.Id;
                }
                NoteSegmentPayloads.Add((noteSegmentPayload as NoteSegmentPayload));
            }
            return noteSegmentPayload;
        }
        return noteSegmentPayload;
    }

}



笔记片段负载实体

笔记片段负载与笔记片段实体为一对多的关系，用于存储笔记片段的详细内容。

定义于\MatoProductivity.Core\Models\Entities\NoteSegmentPayload.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
public class NoteSegmentPayload : FullAuditedEntity<long>, INoteSegmentPayload
{
    public NoteSegmentPayload()
    {

    }


    public NoteSegmentPayload(string key, object value, string valuetype = null)
    {
        if (value is string)
        {
            this.SetStringValue((value as string).ToString());
        }
        else if (value is byte[])
        {
            this.Value = value as byte[];
        }
        else if (value is DateTime)
        {
            this.SetStringValue(((DateTime)value).ToString("yyyy-MM-dd HH:mm:ss"));
        }
        else
        {
            this.SetStringValue(value.ToString());
        }
        this.Key = key;
        this.ValueType = valuetype;

    }




    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    [ForeignKey(nameof(NoteSegmentId))]
    public NoteSegment NoteSegment { get; set; }

    public long NoteSegmentId { get; set; }

    public string Key { get; set; }

    public byte[] Value { get; set; }

    public string ValueType { get; set; }

    [NotMapped]
    public string StringValue => GetStringValue();

    public T GetConcreteValue<T>() where T : struct
    {
        var value = Encoding.UTF8.GetString(Value);
        T result = value.To<T>();
        return result;
    }

    public string GetStringValue()
    {
        var value = Encoding.UTF8.GetString(Value);
        return value;
    }

    public void SetStringValue(string value)
    {
        this.Value = Encoding.UTF8.GetBytes(value);
    }
}

笔记片段仓库实体

用于在编辑笔记页面的添加片段菜单中，加载所有可用的片段

定义于\MatoProductivity.Core\Models\Entities\NoteSegmentStore.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public class NoteSegmentStore : Entity<long>
{
    
    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }
    public string Title { get; set; }
    public string Type { get; set; }
    public string Category { get; set; }
    public string Status { get; set; }
    public string Desc { get; set; }
    public string Icon { get; set; }
    public string Color { get; set; }
    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }


}


笔记模板（场景）实体

定义于\MatoProductivity.Core\Models\Entities\NoteTemplate.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
public class NoteTemplate : FullAuditedEntity<long>
{
    public NoteTemplate()
    {

    }
    public NoteTemplate(string name, bool isHidden, bool isRemovable)
    {
        Title = name;
        IsHidden = isHidden;
        IsRemovable = isRemovable;
    }
    
    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    public ICollection<NoteSegmentTemplate> NoteSegmentTemplates { get; set; }

    public string Title { get; set; }
    public string Type { get; set; }
    public string Status { get; set; }
    public string Desc { get; set; }
    public string Icon { get; set; }
    public string Color { get; set; }
    public string BackgroundColor { get; set; }
    public string BackgroundImage { get; set; }

    public string PreViewContent { get; set; }

    public bool IsEditable { get; set; }

    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }

    public bool CanSimplified { get; set; }


}


笔记片段模板实体

定义于\MatoProductivity.Core\Models\Entities\NoteSegmentTemplate.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
public class NoteSegmentTemplate : FullAuditedEntity<long>, INoteSegment
{
    public NoteSegmentTemplate()
    {

    }



    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    [ForeignKey(nameof(NoteTemplateId))]
    public NoteTemplate NoteTemplate { get; set; }

    public ICollection<NoteSegmentTemplatePayload> NoteSegmentTemplatePayloads { get; set; }

    public long NoteTemplateId { get; set; }

    public string Title { get; set; }
    public string Type { get; set; }
    public string Status { get; set; }
    public string Desc { get; set; }
    public string Icon { get; set; }
    public string Color { get; set; }
    public int Rank { get; set; }

    public bool IsHidden { get; set; }

    public bool IsRemovable { get; set; }


    public INoteSegmentPayload GetNoteSegmentPayload(string key)
    {
        if (NoteSegmentTemplatePayloads != null)
        {
            return NoteSegmentTemplatePayloads.FirstOrDefault(c => c.Key == key);
        }
        return default;
    }

    public void SetNoteSegmentPayload(INoteSegmentPayload noteSegmentPayload)
    {
        if (NoteSegmentTemplatePayloads != null)
        {
            var currentPayload = NoteSegmentTemplatePayloads.FirstOrDefault(c => c.Key == noteSegmentPayload.Key);
            if (currentPayload != null)
            {
                NoteSegmentTemplatePayloads.Remove(currentPayload);
            }
            if (!this.IsTransient())
            {
                (noteSegmentPayload as NoteSegmentTemplatePayload).NoteSegmentTemplateId = this.Id;
            }
            NoteSegmentTemplatePayloads.Add((noteSegmentPayload as NoteSegmentTemplatePayload));
        }
    }

    public INoteSegmentPayload GetOrSetNoteSegmentPayload(string key, INoteSegmentPayload noteSegmentPayload)
    {
        if (NoteSegmentTemplatePayloads != null)
        {
            var currentPayload = NoteSegmentTemplatePayloads.FirstOrDefault(c => c.Key == key);
            if (currentPayload != null)
            {
                return currentPayload;
            }
            if (noteSegmentPayload != null)
            {
                if (!this.IsTransient())
                {
                    (noteSegmentPayload as NoteSegmentTemplatePayload).NoteSegmentTemplateId = this.Id;
                }
                NoteSegmentTemplatePayloads.Add((noteSegmentPayload as NoteSegmentTemplatePayload));
            }
            return noteSegmentPayload;
        }
        return noteSegmentPayload;
    }

}


笔记片段模板负载实体

定义于\MatoProductivity.Core\Models\Entities\NoteSegmentTemplatePayload.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
public class NoteSegmentTemplatePayload : FullAuditedEntity<long>, INoteSegmentPayload
{
    public NoteSegmentTemplatePayload()
    {

    }



    public NoteSegmentTemplatePayload(string key, object value, string valuetype = null)
    {
        if (value is string)
        {
            this.SetStringValue((value as string).ToString());
        }
        else if (value is byte[])
        {
            this.Value = value as byte[];
        }
        else if (value is DateTime)
        {
            this.SetStringValue(((DateTime)value).ToString("yyyy-MM-dd HH:mm:ss"));
        }
        else
        {
            this.SetStringValue(value.ToString());
        }
        this.Key = key;
        this.ValueType = valuetype;

    }



    [Key, DatabaseGenerated(DatabaseGeneratedOption.Identity)]
    public override long Id { get; set; }

    [ForeignKey(nameof(NoteSegmentTemplateId))]
    public NoteSegmentTemplate NoteSegmentTemplate { get; set; }

    public long NoteSegmentTemplateId { get; set; }

    public string Key { get; set; }

    public byte[] Value { get; set; }

    public string ValueType { get; set; }

    [NotMapped]
    public string StringValue => GetStringValue();

    public T GetConcreteValue<T>() where T : struct
    {
        var value = Encoding.UTF8.GetString(Value);
        T result = value.To<T>();
        return result;
    }

    public string GetStringValue()
    {
        var value = Encoding.UTF8.GetString(Value);
        return value;
    }

    public void SetStringValue(string value)
    {
        this.Value = Encoding.UTF8.GetBytes(value);
    }
}


配置EF

数据库上下文对象MatoProductivityDbContext定义如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public class MatoProductivityDbContext : AbpDbContext
{
    //Add DbSet properties for your entities...

    public DbSet<Note> Note { get; set; }
    public DbSet<NoteGroup> NoteGroup { get; set; }
    public DbSet<NoteSegment> NoteSegment { get; set; }
    public DbSet<NoteSegmentStore> NoteSegmentStore { get; set; }
    public DbSet<NoteSegmentPayload> NoteSegmentPayload { get; set; }
    public DbSet<NoteTemplate> NoteTemplate { get; set; }
    public DbSet<NoteSegmentTemplate> NoteSegmentTemplate { get; set; }
    public DbSet<NoteSegmentTemplatePayload> NoteSegmentTemplatePayload { get; set; }
    public DbSet<Theme> Theme { get; set; }
    public DbSet<Setting> Setting { get; set; }
    public MatoProductivityDbContext(DbContextOptions<MatoProductivityDbContext> options) 
        : base(options)
    {

    }
}

MatoProductivity.EntityFrameworkCore是应用程序数据库的维护和管理项目，依赖于Abp.EntityFrameworkCore。
在MatoProductivity.EntityFrameworkCore项目中csproj文件中，引用下列包

1
2
3
4
5
<PackageReference Include="Abp.EntityFrameworkCore" Version="7.4.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite.Design" Version="1.1.6" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0">

在该项目MatoProductivityEntityFrameworkCoreModule.cs 中，将注册上下文对象，并在程序初始化运行迁移，此时将在设备上生成mato.db文件

1
2
3
4
5
6
7
8
9
10
11
12
13
public override void PostInitialize()
{
    Helper.WithDbContextHelper.WithDbContext<MatoProductivityDbContext>(IocManager, RunMigrate);
    if (!SkipDbSeed)
    {
        SeedHelper.SeedHostDb(IocManager);
    }
}

public static void RunMigrate(MatoProductivityDbContext dbContext)
{
    dbContext.Database.Migrate();
}

创建映射

从场景到笔记，或者说从模板到实例，我们需要映射，例如从笔记片段菜单中选择一个片段添加，那么需要从笔记片段仓库实体（NoteSegmentStore）映射到笔记片段实体（NoteSegment）或者，在编辑场景中，映射到笔记片段模板实体（NoteSegmentTemplate）。

1
2
3
4
5
6
[AutoMapTo(typeof(NoteSegment), typeof(NoteSegmentTemplate))]

public class NoteSegmentStore : Entity<long>
{
    ...
}

使用时：

1
var note = ObjectMapper.Map<NoteSegment>(noteSegmentStore);

ABP框架默认使用AutoMapper进行映射，所以需要配置映射关系。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
Configuration.Modules.AbpAutoMapper().Configurators.Add(config =>
{
    IgnoreAbpProperties(config.CreateMap<NoteTemplate, Note>()
    .ForMember(
        c => c.NoteSegments,
        options => options.MapFrom(input => input.NoteSegmentTemplates))
      .ForMember(
        c => c.Id,
        options => options.Ignore()));


    IgnoreAbpProperties(config.CreateMap<Note, NoteTemplate>()
       .ForMember(
           c => c.NoteSegmentTemplates,
           options => options.MapFrom(input => input.NoteSegments))
      .ForMember(
        c => c.Id,
        options => options.Ignore()));


    IgnoreAbpProperties(config.CreateMap<NoteSegmentTemplate, NoteSegment>()
    .ForMember(
        c => c.Note,
        options => options.MapFrom(input => input.NoteTemplate))
    .ForMember(
        c => c.NoteSegmentPayloads,
        options => options.MapFrom(input => input.NoteSegmentTemplatePayloads))
     .ForMember(
        c => c.NoteId,
        options => options.Ignore())
      .ForMember(
        c => c.Id,
        options => options.Ignore()));

    IgnoreAbpProperties(config.CreateMap<NoteSegmentStore, NoteSegment>()
     .ForMember(
       c => c.Id,
       options => options.Ignore()));

    IgnoreAbpProperties(config.CreateMap<NoteSegment, NoteSegmentTemplate>()
       .ForMember(
        c => c.NoteTemplate,
        options => options.MapFrom(input => input.Note))
       .ForMember(
        c => c.NoteTemplateId,
        options => options.Ignore())
       .ForMember(
           c => c.NoteSegmentTemplatePayloads,
           options => options.MapFrom(input => input.NoteSegmentPayloads))
      .ForMember(
        c => c.Id,
        options => options.Ignore()));

    IgnoreAbpProperties(config.CreateMap<NoteSegmentTemplatePayload, NoteSegmentPayload>()
       .ForMember(
           c => c.NoteSegment,
           options => options.MapFrom(input => input.NoteSegmentTemplate))
       .ForMember(
        c => c.NoteSegmentId,
        options => options.Ignore())

      .ForMember(
        c => c.Id,
        options => options.Ignore()));

    IgnoreAbpProperties(
    config.CreateMap<NoteSegmentPayload, NoteSegmentTemplatePayload>()
       .ForMember(
           c => c.NoteSegmentTemplate,
           options => options.MapFrom(input => input.NoteSegment))
       .ForMember(
        c => c.NoteSegmentTemplateId,
        options => options.Ignore()));



});

迁移和种子数据

MatoProductivity.EntityFrameworkCore.Seed.SeedHelper可在程序启动时，访问数据库，并初始化种子数据。

1
2
3
4
5
6
7
8
public override void PostInitialize()
{
    Helper.WithDbContextHelper.WithDbContext<MatoProductivityDbContext>(IocManager, RunMigrate);
    if (!SkipDbSeed)
    {
        SeedHelper.SeedHostDb(IocManager);
    }
}

它通过SkipDbSeed来决定是否跳过执行种子数据初始化。我们需要在安装完成App后第一次运行才执行种子数据初始化。

MAUI中提供了VersionTracking.Default.IsFirstLaunchEver方式获取是否是第一次在此设备上启动应用，请查看官方文档

1
2
3
4
5
6
7
8
9
10
11
12
13
public override async void Initialize()
{
    IocManager.RegisterAssemblyByConvention(typeof(MatoProductivityModule).GetAssembly());
    if (VersionTracking.Default.IsFirstLaunchEver)
    {
        MatoProductivityEntityFrameworkCoreModule.SkipDbSeed = false;
    }
    else
    {
        MatoProductivityEntityFrameworkCoreModule.SkipDbSeed = true;

    }
}

在InitialDbBuilder中我们定义了大多数的业务初始数据，具体的实现方式请查阅源码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
internal void Create()
{

    CreateSetting("Theme", "Light");
    CreateSetting("DetailPageMode", "PreviewPage");


    CreateNoteSegmentStore("时间戳", "时间/提醒", "DateTimeSegment", "记录一个瞬时时间", FaIcons.IconClockO, "#D8292B");
    CreateNoteSegmentStore("计时器", "时间/提醒", "TimerSegment", "创建一个计时器，当它结束时会通知您", FaIcons.IconBell, "#D8292B");
    CreateNoteSegmentStore("笔记", "文本", "TextSegment", "随时用文本记录您的想法", FaIcons.IconStickyNoteO, "#E1A08B");
    CreateNoteSegmentStore("Todo", "文本", "TodoSegment", "记录一个Todo项目", FaIcons.IconCheckSquareO, "#E1A08B");
    CreateNoteSegmentStore("数值", "文本", "KeyValueSegment", "记录数值，以便统计数据", FaIcons.IconLineChart, "#E1A08B");
    CreateNoteSegmentStore("手绘", "文件", "ScriptSegment", "创建一个手绘", FaIcons.IconPaintBrush, "#AD9CC2");
    CreateNoteSegmentStore("照片/视频", "文件", "MediaSegment", "拍照或摄像", FaIcons.IconCamera, "#AD9CC2");
    CreateNoteSegmentStore("文档", "文件", "DocumentSegment", "从您设备中选取一个文档", FaIcons.IconFile, "#AD9CC2");
    CreateNoteSegmentStore("录音", "文件", "VoiceSegment", "记录一段声音", FaIcons.IconMicrophone, "#AD9CC2");
    CreateNoteSegmentStore("地点", "其它", "LocationSegment", "获取当前地点，或者从地图上选取一个地点", FaIcons.IconMapMarker, "#6D987C");
    CreateNoteSegmentStore("天气", "其它", "WeatherSegment", "获取当前天气信息", FaIcons.IconCloud, "#6D987C");
    CreateNoteSegmentStore("联系人", "其它", "ContactSegment", "从您设备的通讯录中选择一个联系人", FaIcons.IconUser, "#6D987C");
}

项目地址

GitHub:MatoProductivity

]]> 从场景到笔记，或者说从模板到实例，我们需要映射，例如从笔记片段菜单中选择一个片段添加，那么需要从笔记片段仓库实体（NoteSegmentStore）映射到笔记片段实体（NoteSegment）或者，在编辑场景中，映射到笔记片段模板实体（NoteSegmentTemplate）。在该项目MatoProductivityEntityFrameworkCoreModule.cs 中，将注册上下文对象，并在程序初始化运行迁移，此时将在设备上生成。可在程序启动时，访问数据库，并初始化种子数据。 [MAUI 项目实战] 笔记App（一）：介绍与程序设计 https://blog.matoapp.net/posts/e3d2e51e/ 2024-07-18T16:37:00.000Z 2025-09-24T16:30:02.406Z

系列文章：

[MAUI 项目实战] 笔记App（一）：介绍与程序设计
[MAUI 项目实战] 笔记App（二）：数据库设计

前言

有人说现在记事类app这么多，市场这么卷，为什么还想做一个笔记类App？

一来，去年小孩刚出生，需要一个可以记录喂奶时间的app，发现市面上没有一款app能够在两步内简单记录一个时间，可能iOS可以通过备忘录配合捷径做到快速记录，但是安卓上就没有类似的app。

二是，自去年做的音乐播放器以来，很长一段时间我在博客上的XF，MAUI都是在介绍局部的功能，[MAUI 项目实战]专题也很长没更新了，这次通过笔记类App做一次完整项目，包括如何上架MAUI应用等内容一并更新了。

一开始用MAUI简单做了一个功能，就记录喂奶量 + 喂奶时间 + 提醒。后期逐步做成一个可以动态添加摘要片段的功能。取名为《凡事摘要》。

目前安卓版本已发布打包，并上架腾讯应用商城：凡事摘要，iOS版本的部分页面还有问题需要调试，最近比较忙，我会抽出时间继续完善。在这个时间点我决定把App所有的代码都放在GitHub上，方便大家学习。也欢迎有兴趣的小伙伴一起参与。

软件规格说明

主要功能

  • 笔记管理：新增笔记，编辑笔记标题，增加笔记片段，修改笔记片段内容，删除笔记等功能。
  • 场景管理：新增场景，编辑场景标题，封面等，增加场景片段，修改场景片段内容，删除场景等功能。
  • 数据统计：查看统计数据。
  • 应用快捷入口管理：增加或删除场景快捷方式。
  • 其它设置：换肤，是否显示预览页面等

运行环境

运行环境为Android 10.0及以上版本，ARM架构CPU，四核2.0GHz， 4GB内存，16GB存储空间，5.5英寸及以上LCD显示屏的Android设备。

开源组件库

组件库名称
.NET Runtime
C#/WinRT
Xamarin.Forms
ASP.NET Core Blazor
AutoMapper
ASP.NET Boilerplate (Abp)
CommunityToolkit.Maui
Castle.Windsor
Newtonsoft.Json
Microsoft.EntityFrameworkCore

设备权限

权限名称使用目的使用场景
设备GPS传感器信息获取当前地理位置用于地址解析创建笔记
设读取设备或存储卡中的内容上传图片时获取用户相册图片文件APP前台运行时
相机上传图片时通过设备相机获取图片创建笔记
读取联系人创建联系人片段时读取设备联系人信息创建笔记
录制音频创建声音片段时通过麦克风录制音频创建笔记

第三方服务

服务名称服务资源服务内容链接
百度智能云用户创建的音频提供语音转文字服务https://cloud.baidu.com/
和风天气用户当前地理位置提供本地天气信息https://www.qweather.com
高德开放平台用户当前地理位置提供当前地理位置的地址解析服务https://lbs.amap.com/

使用介绍

场景列表页

场景列表页用于呈现所有场景，软件默认会有一些场景，用户可以添加新的场景，也可以删除场景。

从场景创建笔记

用户在“场景”页面点击场景列表中的条目，可创建对应场景的笔记。如在点击“喂奶”场景，软件会创建一条笔记，并跳转到编辑页面，点击“保存”按钮，在笔记列表中会呈现此笔记。

编辑场景

编辑场景可对现有场景进行修改，包括修改场景名称，封面，增加、删除、修改场景片段。
点击“…”按钮，打开编辑场景页面，编辑完成后，点击“保存”按钮完成编辑

新增场景片段

在编辑场景页面，点击“+”按钮，可新增场景片段。如在弹出的片段列表中，点击“笔记”

编辑场景片段

在编辑场景页面，点击片段标题可修改标题内容，按住片段右侧的按钮可拖拽，在其它位置释放手指可完成排序。

删除场景片段

在编辑场景页面，向左滑动片段，点击“删除”按钮，即可完成片段删除

删除场景

在编辑场景页面，点击“删除”按钮，或在场景列表页面，长按场景条目，点击“-”按钮，即可完成场景删除

笔记列表页

笔记列表页用于呈现所有笔记，用户可以添加新的笔记，也可以编辑或删除现有的笔记。

创建新笔记

在笔记列表页面点击“+”按钮，可创建一条新的笔记。此时，软件会跳转到编辑页面，点击“保存”按钮，在笔记列表中会呈现此笔记。

编辑笔记

编辑笔记可对现有笔记进行修改，包括修改笔记标题，增加、删除、修改笔记片段。
在笔记列表页中，向左滑动笔记条目，点击“编辑”按钮，打开编辑笔记页面，编辑完成后，点击“保存”按钮完成编辑

新增笔记片段

在编辑笔记页面，点击“+”按钮，可新增笔记片段。如在弹出的片段列表中，点击“笔记”

编辑笔记片段

在编辑笔记页面，点击片段标题可修改标题内容，按住片段右侧的按钮可拖拽，在其它位置释放手指可完成排序。

删除笔记片段

在编辑笔记页面，向左滑动片段，点击“删除”按钮，即可完成片段删除

删除笔记

在笔记列表页向左滑动笔记条目，点击“删除”按钮，或在编辑笔记页面，点击“删除”按钮，即可完成笔记删除

统计

笔记中的数值片段中的数值，可以进行统计。
在笔记编辑页面，添加一个数值片段，输入数值并保存，切换到统计页面，可以看到这些数值为纵轴、时间为横轴的趋势图

其它设置

PIN到快捷方式

对于符合“快速创建”的场景，用户可以在“场景”页面，点击“PIN到快捷方式”按钮，将场景添加到桌面快捷方式，方便用户快速创建笔记。

换肤功能

软件支持换肤功能，用户可以在“我的”页面，点击“黑暗”、“明亮”或“自动”按钮切换软件主题。

程序设计

框架

使用Abp框架，我之前写过如何 将Abp移植进.NET MAUI项目，本项目也是按照这篇博文完成项目搭建。

这次的项目，主要通过原型和工厂模式建设基于模板的笔记内容。

没有使用过多的跨平台特性，如果需要了解更多MAUI跨平台知识，请参考之前音乐播放器系列文章。

定义

  • Note - 笔记，可以成整页打开的内容
  • NoteTemplate - 笔记模板，或称为场景，是可以快速创建笔记的模板
  • NoteSegment - 笔记片段，它是一个笔记（Note）的组成
  • NoteSegmentTemplate - 笔记片段模板，对应场景中可快速创建笔记片段的模板
  • NoteSegmentPayload - 笔记片段负载，存储具体笔记片段的内容
  • NoteSegmentService - 笔记片段服务类，为笔记片段，或笔记片段模板提供增删改等具体的业务逻辑
  • NoteSegmentServiceFactory - 笔记片段服务工厂，为笔记片段服务类提供工厂方法

核心类

INoteSegment：它是笔记片段的抽象类，模板类NoteSegmentTemplate和笔记片段类NoteSegment都实现了INoteSegment

它包含了笔记片段的属性，如标题、颜色、图标、是否隐藏、是否可删除、排序、状态、类型等。同时它关联一个笔记片段负载类INoteSegmentPayload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public interface INoteSegment
{
    string Color { get; set; }
    string Desc { get; set; }
    string Icon { get; set; }
    bool IsHidden { get; set; }
    bool IsRemovable { get; set; }
    int Rank { get; set; }
    string Status { get; set; }
    string Title { get; set; }
    string Type { get; set; }

    INoteSegmentPayload GetNoteSegmentPayload(string key);
    INoteSegmentPayload GetOrSetNoteSegmentPayload(string key, INoteSegmentPayload noteSegmentPayload);
    void SetNoteSegmentPayload(INoteSegmentPayload noteSegmentPayload);
}

INoteSegementService：凡事摘要拥有不同的笔记类型，如：时间戳片段，文本片段，文件片段等，App中可以通过添加片段按钮查看所有类型。

这些片段通过片段服务类（NoteSegementService）来描述该如何存储，使用Payload中的数据。

不同的片段类型，通过不同的片段服务类来实现。比如，在时间戳片段中，我们要存储当前时间和计算倒计时，而文件片段中，我们要存储文件路径，文件名，文件大小，文件类型等信息。

这些都是通过片段服务类来实现的。

具体类型如下：

类型描述
DateTimeSegmentService时间戳片段服务类
KeyValueSegmentService数值片段服务类
FileSegmentService文件片段服务类
TextSegmentService文本片段服务类
TodoSegmentService待办片段服务类
WeatherSegmentService天气片段服务类
LocationSegmentService地点片段服务类
TimerSegmentService闹钟片段服务类
ContactSegmentService联系人片段服务类
VoiceSegmentService录音片段服务类
MediaSegmentService媒体片段服务类
ScriptSegmentService绘制片段服务类
DocumentSegmentService文件片段服务类

片段服务类包含了一个INoteSegment，它是当前的笔记片段对象

INoteSegmentServiceFactory:

片段服务类的工厂类，除此之外还有一个INoteSegmentTemplateServiceFactory，他们都是根据笔记片段，或者笔记模板中的片段类型创建对应的片段服务类。

用于笔记的片段服务类的工厂类:

1
2
3
4
public interface INoteSegmentServiceFactory: ISingletonDependency
{
    INoteSegmentService GetNoteSegmentService(NoteSegment noteSegment);
}

用于笔记模板的片段服务类的工厂类

1
2
3
4
public interface INoteSegmentTemplateServiceFactory: ISingletonDependency
{
    INoteSegmentService GetNoteSegmentService(NoteSegmentTemplate noteSegmentTemplate);
}

NoteSegmentService作为笔记片段服务的基类，它继承了ViewModelBase，实际上服务基类是各笔记片段视图层的ViewModel，视图界面元素通过绑定服务类中的属性来显示或更新数据。

每一种服务类都对应的一个视图。渲染时，Xaml通过NoteSegmentDataTemplateSelector模板选择器来选择对应的视图。有关界面部分将在另一篇文章介绍。

项目地址

使用和发布请遵循GPL-3.0 license许可，请勿用于商业用途。

GitHub:MatoProductivity

]]> 有人说现在记事类app这么多，市场这么卷，为什么还想做一个笔记类App？一来，去年小孩刚出生，需要一个可以记录喂奶时间的app，发现市面上没有一款app能够在两步内简单记录一个时间，可能iOS可以通过备忘录配合捷径做到快速记录，但是安卓上就没有类似的app。二是，自去年做的音乐播放器以来，很长一段时间我在博客上的XF，MAUI都是在介绍局部的功能，[MAUI 项目实战]专题也很长没更新了，这次通过笔记类App做一次完整项目，包括如何上架MAUI应用等内容一并更新了。 OAuth 2.0 的四种方式 https://blog.matoapp.net/posts/eaf19731/ 2024-05-12T22:49:23.000Z 2025-09-24T16:30:02.358Z RFC 6749

OAuth 2.0 的标准是 RFC 6749 文件。该文件先解释了 OAuth 是什么。

OAuth 引入了一个授权层，用来分离两种不同的角色：客户端和资源所有者。……资源所有者同意以后，资源服务器可以向客户端颁发令牌。客户端通过令牌，去请求数据。

这段话的意思就是，OAuth 的核心就是向第三方应用颁发令牌。然后，RFC 6749 接着写道：

（由于互联网有多种场景，）本标准定义了获得令牌的四种授权方式（authorization grant ）。

也就是说，OAuth 2.0 规定了四种获得令牌的流程。你可以选择最适合自己的那一种，向第三方应用颁发令牌。下面就是这四种授权方式。

  • 授权码（authorization-code）
  • 隐藏式（implicit）
  • 密码式（password）：
  • 客户端凭证（client credentials）

注意，不管哪一种授权方式，第三方应用申请令牌之前，都必须先到系统备案，说明自己的身份，然后会拿到两个身份识别码：客户端 ID（client ID）和客户端密钥（client secret）。这是为了防止令牌被滥用，没有备案过的第三方应用，是不会拿到令牌的。

第一种授权方式：授权码

授权码（authorization code）方式，指的是第三方应用先申请一个授权码，然后再用该码获取令牌。

这种方式是最常用的流程，安全性也最高，它适用于那些有后端的 Web 应用。授权码通过前端传送，令牌则是储存在后端，而且所有与资源服务器的通信都在后端完成。这样的前后端分离，可以避免令牌泄漏。

第一步，A 网站提供一个链接，用户点击后就会跳转到 B 网站，授权用户数据给 A 网站使用。下面就是 A 网站跳转 B 网站的一个示意链接。

1
2
3
4
5
6

https://b.com/oauth/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=CALLBACK_URL&
  scope=read

上面 URL 中，response_type参数表示要求返回授权码（code），client_id参数让 B 知道是谁在请求，redirect_uri参数是 B 接受或拒绝请求后的跳转网址，scope参数表示要求的授权范围（这里是只读）。

第二步，用户跳转后，B 网站会要求用户登录，然后询问是否同意给予 A 网站授权。用户表示同意，这时 B 网站就会跳回redirect_uri参数指定的网址。跳转时，会传回一个授权码，就像下面这样。

1
2

https://a.com/callback?code=AUTHORIZATION_CODE

上面 URL 中，code参数就是授权码。

第三步，A 网站拿到授权码以后，就可以在后端，向 B 网站请求令牌。

1
2
3
4
5
6
7

https://b.com/oauth/token?
 client_id=CLIENT_ID&
 client_secret=CLIENT_SECRET&
 grant_type=authorization_code&
 code=AUTHORIZATION_CODE&
 redirect_uri=CALLBACK_URL

上面 URL 中，client_id参数和client_secret参数用来让 B 确认 A 的身份（client_secret参数是保密的，因此只能在后端发请求），grant_type参数的值是AUTHORIZATION_CODE，表示采用的授权方式是授权码，code参数是上一步拿到的授权码，redirect_uri参数是令牌颁发后的回调网址。

第四步，B 网站收到请求以后，就会颁发令牌。具体做法是向redirect_uri指定的网址，发送一段 JSON 数据。

1
2
3
4
5
6
7
8
9
10

{    
  "access_token":"ACCESS_TOKEN",
  "token_type":"bearer",
  "expires_in":2592000,
  "refresh_token":"REFRESH_TOKEN",
  "scope":"read",
  "uid":100101,
  "info":{...}
}

上面 JSON 数据中，access_token字段就是令牌，A 网站在后端拿到了。

第二种方式：隐藏式

有些 Web 应用是纯前端应用，没有后端。这时就不能用上面的方式了，必须将令牌储存在前端。RFC 6749 就规定了第二种方式，允许直接向前端颁发令牌。这种方式没有授权码这个中间步骤，所以称为（授权码）”隐藏式”（implicit）。

第一步，A 网站提供一个链接，要求用户跳转到 B 网站，授权用户数据给 A 网站使用。

1
2
3
4
5
6

https://b.com/oauth/authorize?
  response_type=token&
  client_id=CLIENT_ID&
  redirect_uri=CALLBACK_URL&
  scope=read

上面 URL 中，response_type参数为token，表示要求直接返回令牌。

第二步，用户跳转到 B 网站，登录后同意给予 A 网站授权。这时，B 网站就会跳回redirect_uri参数指定的跳转网址，并且把令牌作为 URL 参数，传给 A 网站。

1
2

https://a.com/callback#token=ACCESS_TOKEN

上面 URL 中，token参数就是令牌，A 网站因此直接在前端拿到令牌。

注意，令牌的位置是 URL 锚点（fragment），而不是查询字符串（querystring），这是因为 OAuth 2.0 允许跳转网址是 HTTP 协议，因此存在”中间人攻击”的风险，而浏览器跳转时，锚点不会发到服务器，就减少了泄漏令牌的风险。

这种方式把令牌直接传给前端，是很不安全的。因此，只能用于一些安全要求不高的场景，并且令牌的有效期必须非常短，通常就是会话期间（session）有效，浏览器关掉，令牌就失效了。

第三种方式：密码式

如果你高度信任某个应用，RFC 6749 也允许用户把用户名和密码，直接告诉该应用。该应用就使用你的密码，申请令牌，这种方式称为”密码式”（password）。

第一步，A 网站要求用户提供 B 网站的用户名和密码。拿到以后，A 就直接向 B 请求令牌。

1
2
3
4
5
6

https://oauth.b.com/token?
  grant_type=password&
  username=USERNAME&
  password=PASSWORD&
  client_id=CLIENT_ID

上面 URL 中，grant_type参数是授权方式，这里的password表示”密码式”，username和password是 B 的用户名和密码。

第二步，B 网站验证身份通过后，直接给出令牌。注意，这时不需要跳转，而是把令牌放在 JSON 数据里面，作为 HTTP 回应，A 因此拿到令牌。

这种方式需要用户给出自己的用户名/密码，显然风险很大，因此只适用于其他授权方式都无法采用的情况，而且必须是用户高度信任的应用。

第四种方式：凭证式

最后一种方式是凭证式（client credentials），适用于没有前端的命令行应用，即在命令行下请求令牌。

第一步，A 应用在命令行向 B 发出请求。

1
2
3
4
5

https://oauth.b.com/token?
  grant_type=client_credentials&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET

上面 URL 中，grant_type参数等于client_credentials表示采用凭证式，client_id和client_secret用来让 B 确认 A 的身份。

第二步，B 网站验证通过以后，直接返回令牌。

这种方式给出的令牌，是针对第三方应用的，而不是针对用户的，即有可能多个用户共享同一个令牌。

令牌的使用

A 网站拿到令牌以后，就可以向 B 网站的 API 请求数据了。

此时，每个发到 API 的请求，都必须带有令牌。具体做法是在请求的头信息，加上一个Authorization字段，令牌就放在这个字段里面。

1
2
3

curl -H "Authorization: Bearer ACCESS_TOKEN" \
"https://api.b.com"

上面命令中，ACCESS_TOKEN就是拿到的令牌。

更新令牌

令牌的有效期到了，如果让用户重新走一遍上面的流程，再申请一个新的令牌，很可能体验不好，而且也没有必要。OAuth 2.0 允许用户自动更新令牌。

具体方法是，B 网站颁发令牌的时候，一次性颁发两个令牌，一个用于获取数据，另一个用于获取新的令牌（refresh token 字段）。令牌到期前，用户使用 refresh token 发一个请求，去更新令牌。

1
2
3
4
5
6

https://b.com/oauth/token?
  grant_type=refresh_token&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET&
  refresh_token=REFRESH_TOKEN

上面 URL 中，grant_type参数为refresh_token表示要求更新令牌，client_id参数和client_secret参数用于确认身份，refresh_token参数就是用于更新令牌的令牌。

B 网站验证通过以后，就会颁发新的令牌。

写到这里，颁发令牌的四种方式就介绍完了。下一篇文章会编写一个真实的 Demo，演示如何通过 OAuth 2.0 向 GitHub 的 API 申请令牌，然后再用令牌获取数据。

（正文完）

前端高级开发工程师免费直播课

经过多年的发展，前端工程师的地位日益提升，越来越多的人想往前端的方向发展。

但是，市场对前端工程师的要求也越来越高，深入掌握底层技术的高级前端，才能在市场上找到自己立足之地。

为了帮助大家深入了解高级前端的学习要点，4月22日（周一）到4月29日（下周一），网易云课堂推出了前端进阶免费直播课。

  • 周一（4月22日）：《前端不会点 node 怎么行，node http 模块详解》
  • 周二（4月23日）：《进阶面试必备的三大技术题》
  • 周三（4月24日）：《前端高级工程师核心装备之柯里化》
  • 周四（4月25日）：《手把手带你实现 Vue 的 MVVM》
  • 周五（4月26日）：《JQuery 原理分析》
  • 周六（4月27日）：《用迭代器模式让你的脱离繁重的数据处理 》
  • 周日（4月28日）：《前端性能–JS的防抖节流实现与案例场景》
  • 周一（4月29日）：《阿里巴巴 P5 面试题讲解》

（更多介绍点击这里）

他们邀请了网易资深前端工程师，免费直播分享实战中的经验方法。内容涉及网易内部自定组件库工具分享，前端开发相关知识，深度剖析 JavaScript 等。

这个直播面向前端初、中级开发工程师，每天2个小时，都是一些干货分享并且不收费，建议想进阶的同学坚持学习。大家可以微信扫码，添加助教，获取听课地址。

（完）

]]> <h2><span id="rfc-6749">RFC 6749</span></h2><p>OAuth 2.0 的标准是 <a href="https://tools.ietf.org/html/rfc6749">RFC 6749</a> 文件。该文件先解释了 OAuth 是什 CSS命名规范-BEM https://blog.matoapp.net/posts/7b14e662/ 2024-05-01T17:52:00.000Z 2025-09-24T16:30:02.330Z BEM解决的问题

css的样式应用是全局性的，没有作用域可言。考虑以下场景

场景一：开发一个弹窗组件，在现有页面中测试都没问题，一段时间后，新需求新页面，该页面一打开这个弹窗组件，页面中样式都变样了，一查问题，原来是弹窗组件和该页面的样式相互覆盖了，接下来就是修改覆盖样式的选择器…又一段时间，又开发新页面，每次为元素命名都心惊胆战，求神拜佛，没写一条样式，F5都按多几次，每个组件都测试一遍…

场景二：承接上文，由于页面和弹窗样式冲突了，所以把页面的冲突样式的选择器加上一些结构逻辑，比如子选择器、标签选择器，借此让选择器独一无二。一段时间后，新同事接手跟进需求，对样式进行修改，由于选择器是一连串的结构逻辑，看不过来，嫌麻烦，就干脆在样式文件最后用另一套选择器，加上了覆盖样式…接下来又有新的需求…最后的结果，一个元素对应多套样式，遍布整个样式文件…

以往开发组件，我们都用“重名概率小”或者干脆起个“当时认为是独一无二的名字”来保证样式不冲突，这是不可靠的。

理想的状态下，我们开发一套组件的过程中，我们应该可以随意的为其中元素进行命名，而不必担心它是否与组件以外的样式发生冲突。

BEM解决这一问题的思路在于，由于项目开发中，每个组件都是唯一无二的，其名字也是独一无二的，组件内部元素的名字都加上组件名，并用元素的名字作为选择器，自然组件内的样式就不会与组件外的样式冲突了。

这是通过组件名的唯一性来保证选择器的唯一性，从而保证样式不会污染到组件外。

这也可以看作是一种“硬性约束”，因为一般来说，我们的组件会放置在同一目录下，那么操作系统中，同一目录下文件名必须唯一，这一点也就确保了组件之间不会冲突。

BEM的命名规矩很容易记：block-name__element-name–modifier-name，也就是模块名 + 元素名 + 修饰器名。

一般来说，根据组件目录名来作为组件名字：

比如分页组件：

/app/components/page-btn/

那么该组件模块就名为page-btn，组件内部的元素命名都必须加上模块名，比如：

1
<div class="page-btn"></div> <button type="button" class="page-btn__prev">上一页</button> <!-- ... --> <button type="button" class="page-btn__next">下一页</button> </div>

上面我们用双下划线来明确区分模块名和元素名，当然也可以用单下划线，比如page-btn_prev和page-btn_next。我们只需保留BEM的思想，其命名规范可以任意变通。

一开始了解BEM的时候，可能会产生误解，出现以下不正确的命名方式：

1
<div class="page-btn"> <!-- ... --> <ul class="page-btn__list"> <li class="page-btn__list__item"> <a href="#" class="page-btn__list__item__link">第一页</a> </li> </ul> <!-- ... --> </div>

分页组件有个ul列表名为：page-btn__list，列表里面存放每一页的按钮，名为：page-btn__list__item__link，这是不对的。

首先，有悖BEM命名规范，BEM的命名中只包含三个部分，元素名只占其中一部分，所以不能出现多个元素名的情况，所以上述每一页的按钮名可以改成：page-btn__btn。

其次，有悖BEM思想，BEM是不考虑结构的，比如上面的分页按钮，即使它是在ul列表里面，它的命名也不应该考虑其父级元素。当我们遵循了这个规定，无论父元素名发生改变，或是模块构造发生的改变，还是元素之间层级关系互相变动，这些都不会影响元素的名字。

所以即使需求变动了，分页组件该有按钮还是要有按钮的，DOM构造发生变动，至多也就不同元素的增删减，模块内名称也随之增删减，而不会出现修改名字的情况，也就不会因为名字变动，牵涉到JS文件的修改，或样式文件的修改。

BEM命名好长

BEM的命名中包含了模块名，长长的命名会让HTML标签会显得臃肿。

其实每个使用BEM的开发团队多多少少会改变其命名规范，比如Instagram团队使用的驼峰式:

1
.blockName-elementName--modifierName { /* ... */ }

还有单下划线：

1
.block-name_element-name--modifierName { /* ... */ }

还有修饰器名用单横线连接：

1
.blockName__elementName-modifierName { /* ... */ }

其实这些对缩短命名没有多大的帮助，但我们也无需担心文件体积的问题，由于服务端有gzip压缩，BEM命名相同的部分多，压缩下来的体积不会太大。另外现在都用IDE来编写代码了，有自动提示功能，也无须担心重复的输入过长的名字。

因为命名长，我们是不是可以用子代选择器来代替BEM命名？这样至少在HTML编写时，让HTML标签看起来美观一点。

下面说说子代选择器带来的问题。

子选择器

子代选择器的方式是，通过组件的根节点的名称来选取子代元素。按照这个思路，分页按钮样式可以这么写：

1
2
3
<div class="page-btn"> <!-- ... --> <ul class="list"></ul> <!-- ... --> </div> 

.page-btn { /* ... */ } .page-btn .list { /* ... */ }

HTML看起来美观多了，但这解决了样式冲突问题么？试想下，如果让你来接手这个项目，要增加一个需求，新增一个组件，你命名放心么？

你面临的问题是：你打开组件目录，里面有个分页组件，叫做page-btn，可是你完全不知道要怎么给新组件命名，因为即使新组件模块名与page-btn不一样，也不能保证新组件与分页组件不冲突。

比如新的需求是“新增一个列表组件”，如果该组件的名字叫做list，其根节点的名字叫list，那么这个组件下面写的样式，就很可能和.page-btn .list的样式冲突:

1
.list { /* ... */ }

这还仅仅只有两个组件而已，实际项目中，十几个或几十个组件，难道我们要每个组件都检查一下来“新组件名是否和以往组件的子元素命名冲突了”么？这不现实。

BEM禁止使用子代选择器，以上是原因之一。子代选择器不好的地方还在于，如果层次关系过长，逻辑不清晰，非常不利于维护。为了懒得命名或者追求所谓的“精简代码”，写出下面这种选择器：

1
.page-btn button:first-child {} .page-btn ul li a {} /* ... */ /* 维护代码，新增需求 */ .page-btn .prev {}

用层次关系结构关系来定位元素，可能会因为需求改变而大面积的重写样式文件。试想一下维护这类代码有多么痛苦，我们要一边检查该元素的上下文DOM结构，一边对照着css文件，一一对比，找到该元素对应的样式，也就是说我为了改一个元素的代码，需要不断翻阅HTML文件和CSS文件，可维护性非常之差。更有甚者，来维护这块代码的同事，直接在样式文件最后添加覆盖样式，这会造成一个非常严重的问题了：同一个元素样式零散的分布在文件的不同地方，而且定位该元素的选择器也可能各不相同。

这样的样式文件只会越写越糟糕，可以说，当我们用子代选择器来定位元素时，这个样式文件就已经注定是要被翻来覆去的重构的了，甚至，每个来维护这个文件的人都会将其重构一遍。

子代选择器还会造成权重过大的问题，当我们要做响应式的时候，某个带样式的元素需要适配不同的屏幕，此时，我们还要不断的确认该元素之前的选择器写法！为了覆盖前面权重过大的样式，甚至通过添加额外的类名或标签名来增加权重。可想而知，此后这个样式文件的维护难度就像雪球一样，越滚越大。

如果我们用的是BEM，要覆盖样式很简单：找到要覆盖样式的元素，得知它的类名，在媒体查询中，用它的类名作为选择器，写下覆盖样式，样式就覆盖成功了，不需要担心前面样式的权重过大。

BEM修饰器

根据不同的场景，组件可能会表现出不同的样式。比如分页组件在pc端具有具体的页码以及上下页按钮，但在移动端，因空间有限，可能只保留上下页按钮。我们可以用修饰器来区分这两种情况。默认情况下，分页按钮的类名为page-btn，但在移动端，我们需要加多个类名page-btn–min

1
/* 缩小版分页组件中，具体页码按钮隐去 */ .page-btn--min .page-btn__btn { display: none; } .page-btn--min .page-btn__prev { width: 50%; } .page-btn--min .page-btn__prev { width: 50%; }

上面这种情况用了子代选择器，BEM是不允许这么写的，BEM中修饰器的样式不依赖于任何结构关系，也就是说，元素的状态改变只会影响自身，不对其他元素进行影响，但实际上，这很难做到的。以上的写法不会造成样式冲突的，而且权重的影响也不大。

BEM修饰器代表着元素的状态，但有时候元素的状态需要js来控制，此时遵循规范没有任何好处，比如激活状态，BEM推荐的写法是：

1
.block__element { display: none; } .block__element--active { display: block; }

当用js为该元素添加状态时，我们需要知道该元素的名字block__element，这样我们才能推导出它的激活状态为block__element–active，这是不合理的，因为很多时候我们无法得知元素的名称，所以这时候，我们应该统一js控制状态的类名格式，比如is-active、js-active等等，这些类名只用作标识，不予许有默认的公共样式：

1
.block__element { display: none; } .block__element.is-active { display: block; }

原子类和BEM

BEM可以不需要用到原子类，但是如果已经引入了类似Bootstrap的框架，也没必要强制避免使用原子类，比如“pull-right”、”ellipsis”、“clearfix”等等类，这些类非常实用，和BEM是可以互补的。

在组件开发中其实不推荐使用原子类，因为这会降低组件的可复用性。可复用性的最理想状态就是组件不仅仅在不同的页面中表现一致，在跨项目的情况下，也能够运行良好。如果组件的样式因为依赖于某几个原子类就要依赖整个Bootstrap库，那么组件d 迁移负担就重很多了。

原子类更适合应用在实际页面中，这是因为页面变动大而且不可复用，假设在header中，我们用到了两个组件logo和user-panel（用户操作面板），两个组件分别置于header的左侧和右侧，我们可以这么写：

1
<div class="header clearfix"> <div class="logo pull-left"><!-- ... --></div> <div class="user-panel pull-left"><!-- ... --></div> </div>

header可以封装成一个模块，但它复用程度不高，不能算是组件，所以即使使用原子类也没有关系。在项目中，使用原子类之前应该考虑一下，这个场景是否变动大而且不可复用，如果是的话，我们可以放心的使用原子类。

组件应该是“自洽的”，其本身就应该构成了一个“生态圈”，也就是说，他几乎不需要外部供给，自给自足就能够运转下去。

实际页面中也应该使用BEM

在实际页面中也需要用到BEM命名方法，不然乱起的一个名字很可能就和某一组件冲突了，导致样式相互覆盖。

假如我们有联系页面，路径是/pages/contact/。那么该页面的模块名可以是page-contact，其名下元素均以page-contact__element-name命名。

一般来说，实际页面中只是对组件进行调用，对组件的位置进行调整，但不会对组件内部细节进行修改。但实际情况下，同一个组件在不同页面不同模样的情况也是有的，所以会出现在实际页面中对组件样式进行微调的代码：

1
/* 联系页面对分页按钮进行微调 */ .page-contact .page-btn {}

但更推荐的做法是给分页组件添加一个修饰器，将上面的样式放到修饰器名下，再根据实际情况运用到页面中。

webpack css-loader 解决之道

BEM主要被诟病的一点在于其命名过长，结合Angular这种带有标签指令的框架时，整个HTML看起来会更混乱：

1
<!-- 发帖页面 --> <span ng-repeat="post in postData track by post.id" ng-if="$index === 0" class="page-post__post-item" ng-class="{'page-post__post-item--even': $even}" popover-content=""> </span>

当然，我们可以通过换行来缓解这个问题:

1
<!-- 发帖页面 --> <span ng-repeat="post in postData track by post.id" ng-if="$index === 0" class="page-post__post-item" ng-class="{'page-post__post-item--even': $even}" popover-content=""> </span>

但其实说穿了，BEM保证样式不冲突的核心就是：在元素名中加入唯一的标识。这个标识在BEM中对应的是模块名，也可能是一个独一无二的乱序字符串。

为模块中每个元素名加入标识，这可是重复的工作啊，重复的工作就应该交给机器去做。

webpack加载器css-loader，可在js中读取css样式，自2015年4月份起，该插件加入了placeholder功能，使得该插件可以解决CSS作用域的问题，原理也就是给元素的名称加入唯一的标识。

1
/* 分页组件 */ :local(.prev) {}

css-loader加载器自定义的语法：:local(.identifier){}向外暴露出选择器.prev。在JS代码中，我们可以拿到这个选择器：

1
import styles from './page-btn.css'; var $prevBtn = $('<button class="' \+ styles.prev \+ '">上一页</button>'); // ...

styles.prev返回的是一串独一无二且随机的字符串，该字符串对应着样式文件中的选择器。这名字有悖语义化，但css-loader支持配置字符串的生成格式

]]> CSS命名规范-BEM介绍 [MAUI]集成富文本编辑器Editor.js至.NET MAUI Blazor项目 https://blog.matoapp.net/posts/33414209/ 2024-04-13T23:52:00.000Z 2025-09-24T16:30:02.550Z

Editor.js 是一个基于 Web 的所见即所得富文本编辑器，它由CodeX团队开发。之前写过一篇博文专门介绍过这个编辑器，可以回看：开源好用的所见即所得(WYSIWYG)编辑器：Editor.js。

.NET MAUI Blazor允许使用 Web UI 生成跨平台本机应用。 组件在 .NET 进程中以本机方式运行，并使用本地互操作通道将 Web UI 呈现到嵌入式 Web 视图控件（BlazorWebView）。

这次我们将Editor.js集成到.NET MAUI应用中。并实现只读切换，明/暗主题切换等功能。

使用.NET MAUI实现跨平台支持，本项目可运行于Android、iOS平台。

获取资源

我们先要获取web应用的资源文件（js，css等），以便MAUI的视图呈现标准的Web UI。有两种方式可以获取：

  1. 从源码构建
  2. 从CDN获取

从源码构建

此方法需要首先安装nodejs

克隆Editorjs项目到本地

1
git clone https://github.com/codex-team/editor.js.git

运行

1
npm i

以及 

1
npm run build

等待nodejs构建完成，在项目根目录找到dist/editorjs.umd.js这个就是我们需要的js文件

从CDN获取

从官方CDN获取：

1
https://cdn.jsdelivr.net/npm/@editorjs/editorjs@latest

获取扩展插件

Editor.js中的每个块都由插件提供。有简单的外部脚本，有自己的逻辑。默认Editor.js项目中已包含唯一的 Paragraph 块。其它的工具插件可以单独获取。

同样我们可以找到这些插件的源码编译，或通过CDN获取：

  1. Header
  2. 链接
  3. HTML块
  4. 简单图片（无后端要求）
  5. 图片
  6. 清单
  7. 列表
  8. 嵌入
  9. 引用

创建项目

新建.NET MAUI Blazor项目，命名Editorjs

将editorjs.umd.js和各插件js文件拷贝至项目根目录下wwwroot文件夹，文件结构如下：

在wwwroot创建editorjs_index.html文件，并在body中引入editorjs.umd.js和各插件js文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<body>
    ...
    <script src="lib/editorjs/editorjs.umd.js"></script>
    <script src="lib/editorjs/tools/checklist@latest.js"></script>
    <script src="lib/editorjs/tools/code@latest.js"></script>
    <script src="lib/editorjs/tools/delimiter@latest.js"></script>
    <script src="lib/editorjs/tools/embed@latest.js"></script>
    <script src="lib/editorjs/tools/header@latest.js"></script>
    <script src="lib/editorjs/tools/image@latest.js"></script>
    <script src="lib/editorjs/tools/inline-code@latest.js"></script>
    <script src="lib/editorjs/tools/link@latest.js"></script>
    <script src="lib/editorjs/tools/nested-list@latest.js"></script>
    <script src="lib/editorjs/tools/marker@latest.js"></script>
    <script src="lib/editorjs/tools/quote@latest.js"></script>
    <script src="lib/editorjs/tools/table@latest.js"></script>
</body>

创建控件

创建 EditNotePage.xaml ，EditNotePage类作为视图控件，继承于ContentView，EditNotePage.xaml的完整代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:mato="clr-namespace:Editorjs;assembly=Editorjs"
             xmlns:service="clr-namespace:Editorjs.ViewModels;assembly=Editorjs"
             xmlns:xct="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Name="MainPage"
             x:Class="Editorjs.Controls.EditNotePage">
    <Grid BackgroundColor="{AppThemeBinding Light={StaticResource LightPageBackgroundColor}, Dark={StaticResource DarkPageBackgroundColor}}"
          RowDefinitions="Auto, *, Auto"
          Padding="20, 10, 20, 0">
        <Grid Grid.Row="0"
              Margin="0, 0, 0, 10">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="auto"></ColumnDefinition>
                <ColumnDefinition></ColumnDefinition>
                <ColumnDefinition></ColumnDefinition>
            </Grid.ColumnDefinitions>

            <Entry Grid.Column="1"
                   Placeholder="请输入标题"
                   Margin="10, 0, 0, 0"
                   VerticalOptions="Center"
                   Text="{Binding Title}"
>
            </Entry>


            <HorizontalStackLayout Grid.Column="2"
                                   HeightRequest="60"
                                   VerticalOptions="Center"
                                   HorizontalOptions="End"
                                   Margin="0, 0, 10, 0">
                <StackLayout RadioButtonGroup.GroupName="State"
                             RadioButtonGroup.SelectedValue="{Binding NoteSegmentState,Mode=TwoWay}"
                             Orientation="Horizontal">
                    <RadioButton Value="{x:Static service:NoteSegmentState.Edit}"
                                 Content="编辑">

                    </RadioButton>
                    <RadioButton Value="{x:Static service:NoteSegmentState.PreView}"
                                 Content="预览">

                    </RadioButton>


                </StackLayout>

            </HorizontalStackLayout>


        </Grid>

        <BlazorWebView Grid.Row="1"
                       Margin="-10, 0"
                       x:Name="mainMapBlazorWebView"
                       HostPage="wwwroot/editorjs_index.html">
            <BlazorWebView.RootComponents>
                <RootComponent Selector="#app"
                               x:Name="rootComponent"
                               ComponentType="{x:Type mato:EditorjsPage}" />
            </BlazorWebView.RootComponents>
        </BlazorWebView>


        <ActivityIndicator Grid.RowSpan="4"
                           IsRunning="{Binding Loading}"></ActivityIndicator>
    </Grid>
</ContentView>

创建一个EditNotePageViewModel的ViewModel类，用于处理页面逻辑。代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
public class EditNotePageViewModel : ObservableObject, IEditorViewModel
{
    public Func<Task<string>> OnSubmitting { get; set; }
    public Action<string> OnInited { get; set; }
    public Action OnFocus { get; set; }

    public EditNotePageViewModel()
    {
        Submit = new Command(SubmitAction);

        NoteSegmentState=NoteSegmentState.Edit;
        var content = "";
        using (Stream stream = Assembly.GetExecutingAssembly().GetManifestResourceStream("Editorjs.Assets.sample1.json"))
        {
            if (stream != null)
            {
                using (StreamReader reader = new StreamReader(stream))
                {
                    content = reader.ReadToEnd();                     
                }
            }
        }
        Init(new Note()
        {
            Title = "sample",
            Content=content

        });
    }

    private void Init(Note note)
    {
        if (note != null)
        {
            Title = note.Title;
            Content = note.Content;
        }
        OnInited?.Invoke(this.Content);
    }


    private string _title;

    public string Title
    {
        get { return _title; }
        set
        {
            _title = value;
            OnPropertyChanged();
        }
    }

    
    private string _content;

    public string Content
    {
        get { return _content; }
        set
        {
            _content = value;
            OnPropertyChanged();
        }
    }


    
    private async void SubmitAction(object obj)
    {
        var savedContent = await OnSubmitting?.Invoke();
        if (string.IsNullOrEmpty(savedContent))
        {
            return;
        }
        this.Content=savedContent;

        var note = new Note();
        note.Title = this.Title;
        note.Content = this.Content;
    }
    public Command Submit { get; set; }

}

注意这里的Init方法，用于初始化内容。这里我们读取Editorjs.Assets.sample1.json资源文件作为初始内容。

创建Blazor组件

创建Blazor页面EditorjsPage.razor

在EditorjsPage.razor页面中，我们放置一个div，用于放置编辑器，

razor页面的 @Code 代码段中，放置EditNotePageViewModel属性，以及一个DotNetObjectReference对象，用于在JS中调用C#方法。

1
2
3
4
5
6
7
8
9
10
11
@code {
    [Parameter]
    public IEditorViewModel EditNotePageViewModel { get; set; }
    private DotNetObjectReference<EditorjsPage> objRef;


    protected override void OnInitialized()
    {
        objRef = DotNetObjectReference.Create(this);
    }

初始化

在script代码段中，创建LoadContent函数，用于加载EditorJs的初始内容。

1
2
3
4
<div class="ce-main">
    <div id="editorjs"></div>
</div>

LoadContent中，调用函数window.editor = new window.EditorJS(config)创建一个EditorJS对象，其中config对象包括holder，tools，data等属性，关于EditorJs配置的更多说明请参考官方文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
<script type="text/javascript">
    window.editor = null;
    window.viewService = {
        LoadContent: function (content) {
            var obj = JSON.parse(content);
            var createEdtor = () => {
                window.editor = new window.EditorJS({                 
                    holder: 'editorjs',

                    /**
                     * Tools list
                     */
                    tools: {
                        paragraph: {
                            config: {
                                placeholder: "Enter something"
                            }
                        },

                        header: {
                            class: Header,
                            inlineToolbar: ['link'],
                            config: {
                                placeholder: 'Header'
                            },
                            shortcut: 'CMD+SHIFT+H'
                        },

                        /**
                         * Or pass class directly without any configuration
                         */
                        image: {
                            class: ImageTool
                        },

                        list: {
                            class: NestedList,
                            inlineToolbar: true,
                            shortcut: 'CMD+SHIFT+L'
                        },

                        checklist: {
                            class: Checklist,
                            inlineToolbar: true,
                        },

                        quote: {
                            class: Quote,
                            inlineToolbar: true,
                            config: {
                                quotePlaceholder: '输入引用内容',
                                captionPlaceholder: '引用标题',
                            },
                            shortcut: 'CMD+SHIFT+O'
                        },


                        marker: {
                            class: Marker,
                            shortcut: 'CMD+SHIFT+M'
                        },

                        code: {
                            class: CodeTool,
                            shortcut: 'CMD+SHIFT+C'
                        },

                        delimiter: Delimiter,

                        inlineCode: {
                            class: InlineCode,
                            shortcut: 'CMD+SHIFT+C'
                        },

                        linkTool: LinkTool,

                        embed: Embed,

                        table: {
                            class: Table,
                            inlineToolbar: true,
                            shortcut: 'CMD+ALT+T'
                        },

                    },
                  
                    i18n: {
                        messages: {
                            "ui": {
                                "blockTunes": {
                                    "toggler": {
                                        "Click to tune": "点击转换",
                                        "or drag to move": "拖动调整"
                                    },
                                },
                                "inlineToolbar": {
                                    "converter": {
                                        "Convert to": "转换成"
                                    }
                                },
                                "toolbar": {
                                    "toolbox": {
                                        "Add": "添加",
                                        "Filter": "过滤",
                                        "Nothing found": "无内容"
                                    },
                                    "popover": {
                                        "Filter": "过滤",
                                        "Nothing found": "无内容"
                                    }
                                }
                            },
                            "toolNames": {
                                "Text": "段落",
                                "Heading": "标题",
                                "List": "列表",
                                "Warning": "警告",
                                "Checklist": "清单",
                                "Quote": "引用",
                                "Code": "代码",
                                "Delimiter": "分割线",
                                "Raw HTML": "HTML片段",
                                "Table": "表格",
                                "Link": "链接",
                                "Marker": "突出显示",
                                "Bold": "加粗",
                                "Italic": "倾斜",
                                "InlineCode": "代码片段",
                                "Image": "图片"
                            },
                            "tools": {
                                "link": {
                                    "Add a link": "添加链接"
                                },
                                "stub": {
                                    'The block can not be displayed correctly.': '该模块不能放置在这里'
                                },
                                "image": {
                                    "Caption": "图片说明",
                                    "Select an Image": "选择图片",
                                    "With border": "添加边框",
                                    "Stretch image": "拉伸图像",
                                    "With background": "添加背景",
                                },
                                "code": {
                                    "Enter a code": "输入代码",
                                },
                                "linkTool": {
                                    "Link": "请输入链接地址",
                                    "Couldn't fetch the link data": "获取链接数据失败",
                                    "Couldn't get this link data, try the other one": "该链接不能访问，请修改",
                                    "Wrong response format from the server": "错误响应",
                                },
                                "header": {
                                    "Header": "标题",
                                    "Heading 1": "一级标题",
                                    "Heading 2": "二级标题",
                                    "Heading 3": "三级标题",
                                    "Heading 4": "四级标题",
                                    "Heading 5": "五级标题",
                                    "Heading 6": "六级标题",
                                },
                                "paragraph": {
                                    "Enter something": "请输入笔记内容",
                                },
                                "list": {
                                    "Ordered": "有序列表",
                                    "Unordered": "无序列表",
                                },
                                "table": {
                                    "Heading": "标题",
                                    "Add column to left": "在左侧插入列",
                                    "Add column to right": "在右侧插入列",
                                    "Delete column": "删除列",
                                    "Add row above": "在上方插入行",
                                    "Add row below": "在下方插入行",
                                    "Delete row": "删除行",
                                    "With headings": "有标题",
                                    "Without headings": "无标题",
                                },
                                "quote": {
                                    "Align Left": "左对齐",
                                    "Align Center": "居中对齐",
                                }
                            },
                            "blockTunes": {
                                "delete": {
                                    "Delete": "删除",
                                    'Click to delete': "点击删除"
                                },
                                "moveUp": {
                                    "Move up": "向上移"
                                },
                                "moveDown": {
                                    "Move down": "向下移"
                                },
                                "filter": {
                                    "Filter": "过滤"
                                }
                            },
                        }
                    },

                    /**
                     * Initial Editor data
                     */
                    data: obj
                });

            }
            if (window.editor) {
                editor.isReady.then(() => {
                    editor.destroy();
                    createEdtor();
                });
            }
            else {
                createEdtor();
            }

        },
        DumpContent: async function () {
            outputData = null;
            if (window.editor) {
                if (window.editor.readOnly.isEnabled) {
                    await window.editor.readOnly.toggle();
                }
                var outputObj = await window.editor.save();
                outputData = JSON.stringify(outputObj);
            }
            return outputData;
        },
        SwitchTheme: function () {
            document.body.classList.toggle("dark-mode");
        },

        SwitchState: async function () {
            state = null;
            if (window.editor && window.editor.readOnly) {
                var readOnlyState = await window.editor.readOnly.toggle();
                state = readOnlyState;
            }
            return state;
        },

        Focus: async function (atEnd) {
            if (window.editor) {
                await window.editor.focus(atEnd);
            }
        },

        GetState() {
            if (window.editor && window.editor.readOnly) {
                return window.editor.readOnly.isEnabled;
            }
        },


        Destroy: function () {
            if (window.editor) {
                window.editor.destroy();
            }
        },

    }

    window.initObjRef = function (objRef) {
        window.objRef = objRef;
    }

</script>

保存

创建转存函数DumpContent

1
2
3
4
5
6
7
8
9
10
11
12
DumpContent: async function () {
    outputData = null;
    if (window.editor) {
        if (window.editor.readOnly.isEnabled) {
            await window.editor.readOnly.toggle();
        }
        var outputObj = await window.editor.save();
        outputData = JSON.stringify(outputObj);
    }
    return outputData;
},

销毁

创建销毁函数Destroy

1
2
3
4
5
6

Destroy: function () {
    if (window.editor) {
        window.editor.destroy();
    }
},

编写渲染逻辑

在OnAfterRenderAsync中调用初始化函数，并订阅OnSubmitting和OnInited事件，以便在提交事件触发时保存，以及文本状态变更时重新渲染。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (!firstRender)
        return;
    if (EditNotePageViewModel != null)
    {
        EditNotePageViewModel.PropertyChanged += EditNotePageViewModel_PropertyChanged;
        this.EditNotePageViewModel.OnSubmitting += OnSubmitting;
        this.EditNotePageViewModel.OnInited += OnInited;
        var currentContent = EditNotePageViewModel.Content;

        await JSRuntime.InvokeVoidAsync("viewService.LoadContent", currentContent);
    }

    await JSRuntime.InvokeVoidAsync("window.initObjRef", this.objRef);

}
1
2
3
4
5
6
7
8
9
10
11
12
private async Task<string> OnSubmitting()
{
    var savedContent = await JSRuntime.InvokeAsync<string>("viewService.DumpContent");
    return savedContent;
}



private async void OnInited(string content)
{
    await JSRuntime.InvokeVoidAsync("viewService.LoadContent", content);
}

实现只读/编辑功能

在.NET本机中，我们使用枚举来表示编辑状态。 并在控件上设置一个按钮来切换编辑状态。

1
2
3
4
5
public enum NoteSegmentState
{
    Edit,
    PreView
}

EditNotePageViewModel.cs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
...
private NoteSegmentState _noteSegmentState;

    public NoteSegmentState NoteSegmentState
    {
        get { return _noteSegmentState; }
        set
        {
            _noteSegmentState = value;
            OnPropertyChanged();

        }
    }

EditNotePage.xaml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
...
<StackLayout RadioButtonGroup.GroupName="State"
             RadioButtonGroup.SelectedValue="{Binding NoteSegmentState,Mode=TwoWay}"
             Orientation="Horizontal">
    <RadioButton Value="{x:Static service:NoteSegmentState.Edit}"
                 Content="编辑">

    </RadioButton>
    <RadioButton Value="{x:Static service:NoteSegmentState.PreView}"
                 Content="预览">

    </RadioButton>


</StackLayout>

Editorjs官方提供了readOnly对象，通过toggle()方法，可以切换编辑模式和只读模式。

在创建Editorjs实例时，也可以通过设置readOnly属性为true即可实现只读模式。

切换模式

在razor页面中创建SwitchState函数，用来切换编辑模式和只读模式。

1
2
3
4
5
6
7
8
9
SwitchState: async function () {
    state = null;
    if (window.editor && window.editor.readOnly) {
        var readOnlyState = await window.editor.readOnly.toggle();
        state = readOnlyState;
    }
    return state;
},

获取只读模式状态

在razor页面中创建GetState函数，用来获取编辑模式和只读模式的状态。

1
2
3
4
5
6
7
8

GetState() {
    if (window.editor && window.editor.readOnly) {
        return window.editor.readOnly.isEnabled;
    }
},


响应切换事件

我们监听EditNotePageViewModel 的NoteSegmentState属性变更事件，当状态改变时，调用对应的js方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
private async void EditNotePageViewModel_PropertyChanged(object sender, System.ComponentModel.PropertyChangedEventArgs e)
{
    if (e.PropertyName == nameof(EditNotePageViewModel.NoteSegmentState))
    {
        if (EditNotePageViewModel.NoteSegmentState==NoteSegmentState.PreView)
        {
            var state = await JSRuntime.InvokeAsync<bool>("viewService.GetState");
            if (!state)
            {
                await JSRuntime.InvokeAsync<bool>("viewService.SwitchState");

            }

        }
        else if (EditNotePageViewModel.NoteSegmentState==NoteSegmentState.Edit)
        {
            var state = await JSRuntime.InvokeAsync<bool>("viewService.GetState");
            if (state)
            {
                await JSRuntime.InvokeAsync<bool>("viewService.SwitchState");
            }
        }
    }
}

实现明/暗主题切换

lib/editorjs/css/main.css中，定义了.dark-mode类的样式表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
.dark-mode {
--color-border-light: rgba(255, 255, 255,.08);
--color-bg-main: #212121;
--color-text-main: #F5F5F5;
}

.dark-mode .ce-popover {
    --color-background: #424242;
    --color-text-primary: #F5F5F5;
    --color-text-secondary: #707684;
    --color-border: #424242;
}

.dark-mode .ce-toolbar__settings-btn {
    background: #2A2A2A;
    border: 1px solid #424242;
}

.dark-mode .ce-toolbar__plus {
    background: #2A2A2A;
    border: 1px solid #424242;
}

.dark-mode .ce-popover-item__icon {
    background: #2A2A2A;
}

.dark-mode .ce-code__textarea {
    color: #212121;
    background: #2A2A2A;
}

.dark-mode .tc-popover {
    --color-border: #424242;
    --color-background: #424242;
}
.dark-mode .tc-wrap {
    --color-background: #424242;
}

在razor页面中添加SwitchTheme函数，用于用于切换dark-mode“的`类名，从而实现暗黑模式和正常模式之间的切换。

1
2
3
SwitchTheme: function () {
    document.body.classList.toggle("dark-mode");
},

在OnInitializedAsync中，订阅Application.Current.RequestedThemeChanged事件，用于监听主题切换事件，并调用SwitchTheme函数。

1
2
3
4
5
6
7
8
9
10
11
protected override async Task OnInitializedAsync()
{
    objRef = DotNetObjectReference.Create(this);

    Application.Current.RequestedThemeChanged += OnRequestedThemeChanged;

}
private async void OnRequestedThemeChanged(object sender, AppThemeChangedEventArgs args)
{
    await JSRuntime.InvokeVoidAsync("viewService.SwitchTheme");
}

在渲染页面时，也判断是否需要切换主题

1
2
3
4
5
6
7
8
9
10
11
12
13
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (!firstRender)
        return;
    ···
    if (Application.Current.UserAppTheme==AppTheme.Dark)
    {
        await JSRuntime.InvokeVoidAsync("viewService.SwitchTheme");

    }

}

项目地址

Github:maui-samples

]]> 其它的工具插件可以单独获取。在OnAfterRenderAsync中调用初始化函数，并订阅OnSubmitting和OnInited事件，以便在提交事件触发时保存，以及文本状态变更时重新渲染。在wwwroot创建editorjs_index.html文件，并在body中引入editorjs.umd.js和各插件js文件。我们先要获取web应用的资源文件（js，css等），以便MAUI的视图呈现标准的Web UI。在script代码段中，创建LoadContent函数，用于加载EditorJs的初始内容。 [MAUI]模仿哔哩哔哩的一键三连 https://blog.matoapp.net/posts/a6dfa37/ 2024-03-25T19:43:00.000Z 2025-09-24T16:30:02.514Z

哔哩哔哩(Bilibili)中用户可以通过长按点赞键同时完成点赞、投币、收藏对UP主表示支持，后UP主多用“一键三连”向视频浏览者请求对其作品同时进行点赞、投币、收藏。

“三连按钮”是一组按钮，轻击时当做普通状态按钮使用，当长按 2 秒钟后，转为三连模式，可以控制并显示进度，并在进度完成时弹出一些泡泡

一直想实现这个效果，但由于.NET MAUI对图形填充渲染问题直到.NET 8才修复。想要的效果直到最近才能实现。

两年前Dino老师用UWP实现过“一键三连”:

[UWP]模仿哔哩哔哩的一键三连

今天用MAUI实现。

使用.NET MAU实现跨平台支持，本项目可运行于Android、iOS平台。

创建弧形进度条

新建.NET MAUI项目，命名HoldDownButtonGroup

在项目中添加SkiaSharp绘制功能的引用Microsoft.Maui.Graphics.Skia以及SkiaSharp.Views.Maui.Controls。

1
2
3
4
<ItemGroup>
    <PackageReference Include="Microsoft.Maui.Graphics.Skia" Version="7.0.59" />
    <PackageReference Include="SkiaSharp.Views.Maui.Controls" Version="2.88.3" />
</ItemGroup>

进度条（ProgressBar）用于展示任务的进度，告知用户当前状态和预期，本项目依赖弧形进度条组件（CircleProgressBar），此组件在本项目中用于展示“三连按钮”长按任务的进度

这里简单介绍弧形进度条组件的原理和实现，更多内容请阅读：[MAUI]弧形进度条与弧形滑块的交互实现。

控件将包含以下可绑定属性：

  • Maxiumum：最大值
  • Minimum：最小值
  • Progress：当前进度
  • AnimationLength：动画时长
  • BorderWidth：描边宽度
  • LabelContent：标签内容
  • ContainerColor：容器颜色，即进度条的背景色
  • ProgressColor：进度条颜色

创建CircleProgressBar.xaml，代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="UTF-8"?>
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:forms="clr-namespace:SkiaSharp.Views.Maui.Controls;assembly=SkiaSharp.Views.Maui.Controls"
             x:Class="HoldDownButtonGroup.Controls.CircleProgressBar">
    <ContentView.Content>
        <Grid>
            <forms:SKCanvasView x:Name="canvasView"
                                PaintSurface="OnCanvasViewPaintSurface" />
            <ContentView x:Name="MainContent"></ContentView>
            <Label 
                FontSize="28"
                HorizontalOptions="Center"
                VerticalOptions="Center" 
                x:Name="labelView"></Label>
        </Grid>

    </ContentView.Content>
</ContentView>

SKCanvasView是SkiaSharp.Views.Maui.Controls封装的View控件。

绘制弧

Skia中，通过AddArc方法绘制弧，需要传入一个SKRect对象，其代表一个弧（或椭弧）的外接矩形。startAngle和sweepAngle分别代表顺时针起始角度和扫描角度。

通过startAngle和sweepAngle可以绘制出一个弧，如下图红色部分所示：

在CircleProgressBar.xaml.cs的CodeBehind中，创建OnCanvasViewPaintSurface，通过给定起始角度为正上方，扫描角度为360对于100%进度，通过插值计算出当前进度对应的扫描角度，绘制出进度条。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
private void OnCanvasViewPaintSurface(object sender, SKPaintSurfaceEventArgs args)
{

    var SumValue = Maximum - Minimum;


    SKImageInfo info = args.Info;
    SKSurface surface = args.Surface;
    SKCanvas canvas = surface.Canvas;

    canvas.Clear();

    SKRect rect = new SKRect(_mainRectPadding, _mainRectPadding, info.Width - _mainRectPadding, info.Height - _mainRectPadding);
    float startAngle = -90;
    float sweepAngle = (float)((_realtimeProgress / SumValue) * 360);

    canvas.DrawOval(rect, OutlinePaint);

    using (SKPath path = new SKPath())
    {
        path.AddArc(rect, startAngle, sweepAngle);
        
        canvas.DrawPath(path, ArcPaint);
    }
}

其中SumValue表明进度条的总进度，通过Maximum和Minimum计算得出。

1
2
public double SumValue => Maximum - Minimum;

创建进度条轨道背景画刷和进度条画刷，其中进度条画刷的StrokeCap属性设置为SKStrokeCap.Round，使得进度条两端为圆形。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
protected SKPaint _outlinePaint;

public SKPaint OutlinePaint
{
    get
    {
        if (_outlinePaint == null)
        {
            RefreshMainRectPadding();
            SKPaint outlinePaint = new SKPaint
            {
                Color = this.ContainerColor.ToSKColor(),
                Style = SKPaintStyle.Stroke,
                StrokeWidth = (float)BorderWidth,
            };
            _outlinePaint = outlinePaint;
        }
        return _outlinePaint;
    }
}

protected SKPaint _arcPaint;

public SKPaint ArcPaint
{
    get
    {
        if (_arcPaint == null)
        {
            RefreshMainRectPadding();
            SKPaint arcPaint = new SKPaint
            {
                Color = this.ProgressColor.ToSKColor(),
                Style = SKPaintStyle.Stroke,
                StrokeWidth = (float)BorderWidth,
                StrokeCap = SKStrokeCap.Round,
            };
            _arcPaint = arcPaint;
        }

        return _arcPaint;
    }
}

在Progress值变更时，重新渲染进度条，并触发ValueChanged事件。

1
2
3
4
5
6
7

private void UpdateProgress()
{
    this._realtimeProgress = this.Progress;
    this.labelView.Text = this.Progress.ToString(LABEL_FORMATE);
    this.canvasView?.InvalidateSurface();
}

效果如下

准备物料

点赞、投币、收藏三个按钮的图片来自于哔哩哔哩（Bilibili）网站。这些按钮用svg格式在html中。

我们只需前往哔哩哔哩主站，要打开浏览器的开发者工具，用元素检查器，在找到按钮位置后查看其样式，拷贝path中的svg代码，即可得到这些矢量图片。

拷贝右侧红色区域选中的部分，我们只需要这些svg代码。

在Xaml中我们创建Path元素，并设置Data属性为svg代码。即可得到一个图形

1
2
3
4
5
6
7
8
<Path HeightRequest="65"
        WidthRequest="65"
        x:Name="Icon1"
        Fill="Transparent"
        Aspect="Uniform"
        Data="M 9.77234 30.8573 V 11.7471 H 7.54573 C 5.50932 11.7471 3.85742 13.3931 3.85742 15.425 V 27.1794 C 3.85742 29.2112 5.50932 30.8573 7.54573 30.8573 H 9.77234 Z M 11.9902 30.8573 V 11.7054 C 14.9897 10.627 16.6942 7.8853 17.1055 3.33591 C 17.2666 1.55463 18.9633 0.814421 20.5803 1.59505 C 22.1847 2.36964 23.243 4.32583 23.243 6.93947 C 23.243 8.50265 23.0478 10.1054 22.6582 11.7471 H 29.7324 C 31.7739 11.7471 33.4289 13.402 33.4289 15.4435 C 33.4289 15.7416 33.3928 16.0386 33.3215 16.328 L 30.9883 25.7957 C 30.2558 28.7683 27.5894 30.8573 24.528 30.8573 H 11.9911 H 11.9902 Z"
        VerticalOptions="Center"
        HorizontalOptions="Center" />

创建气泡

气泡实现分为两个步骤：

Bubble.xaml 创建单一气泡动画
Bubbles.xaml 包含气泡集群。随机生成气泡动画路径，创建气泡集群的动画

Bubbles控件将包含以下可绑定属性：

  • Brush：气泡颜色
  • BubbleCnt：气泡数量
  • BubbleSize：气泡大小

气泡动画算法参考于火火的 BubbleButton，这里只帖关键代码

单一气泡的动画：先变大后消失

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public Animation GetAnimation()
{

    var scaleAnimation = new Animation();

    var scaleUpAnimation0 = new Animation(v => MainBox.Scale = v, 0, 1);
    var scaleUpAnimation1 = new Animation(v => MainBox.Scale = v, 1, 0);


    scaleAnimation.Add(0, 0.2, scaleUpAnimation0);
    scaleAnimation.Add(0.8, 1, scaleUpAnimation1);

    scaleAnimation.Finished = () =>
    {
        this.MainBox.Scale = 0;
    };

    return scaleAnimation;

}

生成气泡

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public void SpawnBubbles()
{
    this.PitContentLayout.Clear();
    for (int i = 0; i < BubbleCnt; i++)
    {
        var currentBox = new Bubble();
        currentBox.FillColor = i % 2 == 0 ? this.Brush : SolidColorBrush.Transparent;
        currentBox.BorderColor = this.Brush;
        currentBox.HeightRequest = BubbleSize;
        currentBox.WidthRequest = BubbleSize;
        currentBox.HorizontalOptions = LayoutOptions.Start;
        currentBox.VerticalOptions = LayoutOptions.Start;
        this.PitContentLayout.Add(currentBox);
    }
}

计算单个气泡的动画路径：随机产生动画运动的随机坐标

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
private Animation InitAnimation(Bubble element, Size targetSize, bool isOnTop = true)
{


    var offsetAnimation = new Animation();

    if (targetSize == default)
    {
        targetSize = element.DesiredSize;

    }
    var easing = Easing.Linear;

    var originX = PitContentLayout.Width / 2;
    var originY = PitContentLayout.Height / 2;

    var targetX = rnd.Next(-(int)targetSize.Width, (int)targetSize.Width) + (int)targetSize.Width / 2 + originX;
    var targetY = isOnTop ? rnd.Next(-(int)(targetSize.Height * 1.5), 0) + (int)targetSize.Height / 2 + originY :
            rnd.Next(0, (int)(targetSize.Height * 1.5)) + (int)targetSize.Height / 2 + originY
        ;


    var offsetX = targetX - originX;
    var offsetY = targetY - originY;


    var offsetAnimation1 = new Animation(v => element.TranslationX = v, originX - targetSize.Width / 2, targetX - targetSize.Width / 2, easing);
    var offsetAnimation2 = new Animation(v => element.TranslationY = v, originY - targetSize.Height / 2, targetY - targetSize.Height / 2, easing);

    offsetAnimation.Add(0.2, 0.8, offsetAnimation1);
    offsetAnimation.Add(0.2, 0.8, offsetAnimation2);
    offsetAnimation.Add(0, 1, element.BoxAnimation);

    offsetAnimation.Finished = () =>
    {

        element.TranslationX = originX;
        element.TranslationY = originY;
        element.Rotation = 0;
    };

    return offsetAnimation;
}

开始气泡动画

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public void StartAnimation()
{

    Content.AbortAnimation("ReshapeAnimations");
    var offsetAnimationGroup = new Animation();

    foreach (var item in this.PitContentLayout.Children)
    {
        if (item is Bubble)
        {
            var isOntop = this.PitContentLayout.Children.IndexOf(item) > this.PitContentLayout.Children.Count / 2;
            var currentAnimation = InitAnimation(item as Bubble, targetSize, isOntop);
            offsetAnimationGroup.Add(0, 1, currentAnimation);


        }
    }
    offsetAnimationGroup.Commit(this, "ReshapeAnimations", 16, 400);

}

创建手势

可喜可贺，在新发布的.NET 8 中， .NET MAUI 引入了指针手势识别器(PointerGestureRecognizer)，使用方式如下，终于不用自己实现手势监听控件了。

Xaml:

1
2
3
4
5
6
7
<Image Source="dotnet_bot.png">
    <Image.GestureRecognizers>
        <PointerGestureRecognizer PointerEntered="OnPointerEntered"
                                  PointerExited="OnPointerExited"
                                  PointerMoved="OnPointerMoved" />
  </Image.GestureRecognizers>
</Image>

C#:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
void OnPointerEntered(object sender, PointerEventArgs e)
{
    // Handle the pointer entered event
}

void OnPointerExited(object sender, PointerEventArgs e)
{
    // Handle the pointer exited event
}

void OnPointerMoved(object sender, PointerEventArgs e)
{
    // Handle the pointer moved event
}

具体请阅读官方文档：
.NET 8 中 .NET MAUI 的新增功能以及
识别指针手势

在本项目中，需要监听长按动作，当“三连按钮”长按2秒后，转为三连模式，此时需要监听手指释放情况，当时长不足时取消三连。

由于在之前的文章中实现过监听手势，这里仅简单介绍定义，其余内容不再重复，如需了解请阅读： [MAUI程序设计] 用Handler实现自定义跨平台控件

定义可以监听的手势类别，分别是按下、移动、抬起、取消、进入、退出

1
2
3
4
5
6
7
8
9
10

public enum TouchActionType
   {
       Entered,
       Pressed,
       Moved,
       Released,
       Exited,
       Cancelled
   }

添加手势监听器TouchRecognizer，它将提供一个事件OnTouchActionInvoked，用触发手势动作。

1
2
3
4
5
public partial class TouchRecognizer: IDisposable
{
    public event EventHandler<TouchActionEventArgs> OnTouchActionInvoked;
    public partial void Dispose();
}

EventArg类TouchActionEventArgs，用于传递手势动作的参数

创建交互与动效

在页面创建完三个按钮后，在CodeBehind中编写交互逻辑

添加更新圆环进度的方法UpdateProgressWithAnimate，此方法根据圆环进度的百分比，计算圆环进度的动画时间，并开始动画

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

private void UpdateProgressWithAnimate(CircleProgressBar progressElement, double progressTarget = 100, double totalLenght = 5*1000, Action<double, bool> finished = null)
{
    Content.AbortAnimation("ReshapeAnimations");
    var scaleAnimation = new Animation();

    double progressOrigin = progressElement.Progress;

    var animateAction = (double r) =>
    {
        progressElement.Progress = r;
    };

    var scaleUpAnimation0 = new Animation(animateAction, progressOrigin, progressTarget);

    scaleAnimation.Add(0, 1, scaleUpAnimation0);
    var calcLenght = (double)(Math.Abs((progressOrigin - progressTarget) / 100)) * totalLenght;

    scaleAnimation.Commit(progressElement, "ReshapeAnimations", 16, (uint)calcLenght, finished: finished);

}

创建“三连成功”的动画方法StartCelebrationAnimate，在这里通过改变按钮的Scale和Fill属性，实现三连成功时“点亮”图标的动画效果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

private void StartCelebrationAnimate(Path progressElement, Action<double, bool> finished = null)
{
    var toColor = (Color)this.Resources["BrandColor"];
    var fromColor = (Color)this.Resources["DisabledColor"];

    var scaleAnimation = new Animation();

    var scaleUpAnimation0 = new Animation(v => progressElement.Scale=v, 0, 1.5);
    var scaleUpAnimation1 = new Animation(v => progressElement.Fill=GetColor(v, fromColor, toColor), 0, 1);
    var scaleUpAnimation2 = new Animation(v => progressElement.Scale=v, 1.5, 1);

    scaleAnimation.Add(0, 0.5, scaleUpAnimation0);
    scaleAnimation.Add(0, 1, scaleUpAnimation1);
    scaleAnimation.Add(0.5, 1, scaleUpAnimation2);

    scaleAnimation.Commit(progressElement, "CelebrationAnimate", 16, 400, finished: finished);

}

按钮触发TouchContentView_OnTouchActionInvoked事件：

_dispatcherTimer作用是延时1秒，如果按钮被点击，则开始执行后续操作。当按钮被点击时此Timer会开。

一秒后，开始进入“三连模式”，此时更新圆环进度，当进度完成后开始气泡动画和“三连成功”的动画。

若中途按钮被释放，则取消此Timer，并重置圆环进度。

若按钮未进入“三连模式”，则直接播放按钮的点击动画。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
private void TouchContentView_OnTouchActionInvoked(object sender, TouchActionEventArgs e)
{
    var layout = ((Microsoft.Maui.Controls.Layout)(sender as TouchContentView).Content).Children;
    var bubbles = layout[0] as Bubbles;
    var circleProgressBar = layout[1] as CircleProgressBar;


    switch (e.Type)
    {
        case TouchActionType.Entered:
            break;
        case TouchActionType.Pressed:
            _dispatcherTimer =Dispatcher.CreateTimer();
            _dispatcherTimer.Interval=new TimeSpan(0, 0, 1);

            _dispatcherTimer.Tick+=   async (o, e) =>
            {
                _isInProgress=true;
                this.UpdateProgressWithAnimate(ProgressBar1, 100, 2*1000, (d, b) =>
                {
                    if (circleProgressBar.Progress==100)
                    {
                        this.bubbles1.StartAnimation();
                        StartCelebrationAnimate(this.Icon1);
                    }
                });
                this.UpdateProgressWithAnimate(ProgressBar2, 100, 2*1000, (d, b) =>
                {
                    if (circleProgressBar.Progress==100)
                    {
                        this.bubbles2.StartAnimation();
                        StartCelebrationAnimate(this.Icon2);
                    }
                });
                this.UpdateProgressWithAnimate(ProgressBar3, 100, 2*1000, (d, b) =>
                {
                    if (circleProgressBar.Progress==100)
                    {
                        this.bubbles3.StartAnimation();
                        StartCelebrationAnimate(this.Icon3);
                    }
                });

            };

            _dispatcherTimer.Start();


            break;
        case TouchActionType.Moved:
            break;
        case TouchActionType.Released:

            if (!_isInProgress)
            {
                var brandColor = (Color)this.Resources["BrandColor"];
                var disabledColor = (Color)this.Resources["DisabledColor"];

                if (circleProgressBar.Progress==100)
                {
                    this.UpdateProgressWithAnimate(ProgressBar1, 0, 1000);
                    this.UpdateProgressWithAnimate(ProgressBar2, 0, 1000);
                    this.UpdateProgressWithAnimate(ProgressBar3, 0, 1000);
                    (ProgressBar1.LabelContent as Path).Fill=disabledColor;
                    (ProgressBar2.LabelContent as Path).Fill=disabledColor;
                    (ProgressBar3.LabelContent as Path).Fill=disabledColor;


                }
                else
                {
                    if (((circleProgressBar.LabelContent as Path).Fill  as SolidColorBrush).Color==disabledColor)
                    {
                        StartCelebrationAnimate(circleProgressBar.LabelContent as Path);

                    }
                    else
                    {
                        (circleProgressBar.LabelContent as Path).Fill=disabledColor;
                    }
                }


            }
            if (_dispatcherTimer!=null)
            {
                if (_dispatcherTimer.IsRunning)
                {
                    _dispatcherTimer.Stop();
                    _isInProgress=false;

                }
                _dispatcherTimer=null;

                if (circleProgressBar.Progress==100)
                {
                    return;
                }

                this.UpdateProgressWithAnimate(ProgressBar1, 0, 1000);
                this.UpdateProgressWithAnimate(ProgressBar2, 0, 1000);
                this.UpdateProgressWithAnimate(ProgressBar3, 0, 1000);
            }



            break;
        case TouchActionType.Exited:
            break;
        case TouchActionType.Cancelled:
            break;
        default:
            break;
    }
}

进入三联模式动画效果如下：

未进入三联模式动画效果如下：

最终效果如下：

项目地址

Github:maui-samples

]]> 的CodeBehind中，创建OnCanvasViewPaintSurface，通过给定起始角度为正上方，扫描角度为360对于100%进度，通过插值计算出当前进度对应的扫描角度，绘制出进度条。“三连按钮”是一组按钮，轻击时当做普通状态按钮使用，当长按 2 秒钟后，转为三连模式，可以控制并显示进度，并在进度完成时弹出一些泡泡。在本项目中，需要监听长按动作，当“三连按钮”长按2秒后，转为三连模式，此时需要监听手指释放情况，当时长不足时取消三连。当按钮被点击时此Timer会开。这些按钮用svg格式在html中。 [MAUI]集成高德地图组件至.NET MAUI Blazor项目 https://blog.matoapp.net/posts/e6d51e9d/ 2024-03-23T21:58:00.000Z 2025-09-24T16:30:02.558Z

地图组件在手机App中常用地理相关业务，如查看线下门店，设置导航，或选取地址等。是一个较为常见的组件。

在.NET MAUI 中，有两种方案可以集成高德地图，一种是使用原生库绑定。网上也有人实现过：https://blog.csdn.net/sD7O95O/article/details/125827031

但这种方案需要大量平台原生开发的知识，而且需要对每一个平台进行适配。

在这里我介绍第二种方案：.NET MAUI Blazor + 高德地图JS API 2.0 库的实现。

JS API 2.0 是高德开放平台基于WebGL的地图组件，可以将高德地图模块集成到.NET MAUI Blazor中的BlazorWebView控件，由于BlazorWebView的跨平台特性，可以达到一次开发全平台通用，无需为每个平台做适配。

今天用此方法实现一个地图选择器，使用手机的GPS定位初始化当前位置，使用高德地图JS API库实现地点选择功能。混合开发方案涉及本机代码与JS runtime的交互，如果你对这一部分还不太了解，可以先阅读这篇文章：[MAUI]深入了解.NET MAUI Blazor与Vue的混合开发

.NET MAUI Blazor

使用.NET MAU实现跨平台支持，本项目可运行于Android、iOS平台。

前期准备：注册高德开发者并创建 key

登录控制台

登录 高德开放平台控制台，如果没有开发者账号，请 注册开发者。

创建 key

进入应用管理，创建新应用，新应用中添加 key，服务平台选择 Web端(JS API)。再创建一个Web服务类型的Key，用于解析初始位置地址。

获取 key 和密钥

创建成功后，可获取 key 和安全密钥。

创建项目

新建.NET MAUI Blazor项目，命名AMap

创建JS API Loader

前往https://webapi.amap.com/loader.js另存js文件至项目wwwroot文件夹

在wwwroot创建amap_index.html文件，将loader.js引用到页面中。创建_AMapSecurityConfig对象并设置安全密钥。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
    <title>AmapApp</title>
    <base href="/" />
    <link href="css/app2.css" rel="stylesheet" />
</head>

<body>

    <div class="status-bar-safe-area"></div>

    <div id="app">Loading...</div>

    <div id="blazor-error-ui">
        An unhandled error has occurred.
        <a href="" class="reload">Reload</a>
        <a class="dismiss"></a>
    </div>

    <script src="_framework/blazor.webview.js" autostart="false"></script>
    <script src="lib/amap/loader.js"></script>
    <script type="text/javascript">
        window._AMapSecurityConfig = {
            securityJsCode: "764832459a38e824a0d555b62d8ec1f0",
        };
    </script>

</body>

</html>


配置权限

打开Android端AndroidManifest.xml文件

添加权限：

1
2
3
4
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

打开Info.plist文件，添加权限描述信心

1
2
<key>NSLocationWhenInUseUsageDescription</key>
<string>允许使用设备的GPS更新您的位置信息。</string>

创建定义

创建Position，Poi，Location等类型，用于描述位置信息。由于篇幅这里不展开介绍。

创建模型

创建一个MainPageViewModel类，用于处理页面逻辑。代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
public class MainPageViewModel : ObservableObject
{
    public event EventHandler<FinishedChooiseEvenArgs> OnFinishedChooise;
    private static AsyncLock asyncLock = new AsyncLock();
    public static RateLimitedAction throttledAction = Debouncer.Debounce(null, TimeSpan.FromMilliseconds(1500), leading: false, trailing: true);
    public MainPageViewModel()
    {
        Search = new Command(SearchAction);
        Done = new Command(DoneAction);
        Remove = new Command(RemoveAction);
    }

    private void RemoveAction(object obj)
    {
        this.Address=null;
        this.CurrentLocation=null;
        OnFinishedChooise?.Invoke(this, new FinishedChooiseEvenArgs(Address, CurrentLocation));
    }

    private void DoneAction(object obj)
    {
        OnFinishedChooise?.Invoke(this, new FinishedChooiseEvenArgs(Address, CurrentLocation));

    }

    private void SearchAction(object obj)
    {
        Init();
    }

    public async void Init()
    {
        var location = await GeoLocationHelper.GetNativePosition();
        if (location==null)
        {
            return;
        }
        var amapLocation = new Location.Location()
        {
            Latitude=location.Latitude,
            Longitude=location.Longitude
        };
        CurrentLocation=amapLocation;

    }

    private Location.Location _currentLocation;

    public Location.Location CurrentLocation
    {
        get { return _currentLocation; }
        set
        {

            if (_currentLocation != value)
            {
                if (value!=null &&_currentLocation!=null&&Location.Location.CalcDistance(value, _currentLocation)<100)
                {
                    return;
                }

                _currentLocation = value;
                OnPropertyChanged();
            }
        }
    }

    private string _address;

    public string Address
    {
        get { return _address; }
        set
        {
            _address = value;
            OnPropertyChanged();
        }
    }


    private ObservableCollection<Poi> _pois;

    public ObservableCollection<Poi> Pois
    {
        get { return _pois; }
        set
        {
            _pois = value;
            OnPropertyChanged();
        }
    }

    private Poi _selectedPoi;

    public Poi SelectedPoi
    {
        get { return _selectedPoi; }
        set
        {
            _selectedPoi = value;
            OnPropertyChanged();

        }
    }


    public Command Search { get; set; }
    public Command Done { get; set; }
    public Command Remove { get; set; }

}

注意这里的Init方法，用于初始化位置。

GeoLocationHelper.GetNativePosition()方法用于从你设备的GPS模块，获取当前位置。它调用的是Microsoft.Maui.Devices.Sensors提供的设备传感器访问功能
，详情可参考官方文档地理位置 - .NET MAUI

创建地图组件

创建Blazor页面AMapPage.razor以及AMapPage.razor.js

在AMapPage.razor中引入

1
2
3
4
5
6
7
8
9
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (!firstRender)
        return;
    await JSRuntime.InvokeAsync<IJSObjectReference>(
   "import", "./AMapPage.razor.js");
    await Refresh();
    await JSRuntime.InvokeVoidAsync("window.initObjRef", this.objRef);
}

razor页面的 @Code 代码段中，放置MainPageViewModel属性，以及一个DotNetObjectReference对象，用于在JS中调用C#方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@code {
    [Parameter]
    public MainPageViewModel MainPageViewModel { get; set; }
    private DotNetObjectReference<AMapPage> objRef;


    protected override void OnInitialized()
    {
        objRef = DotNetObjectReference.Create(this);
    }

    private async Task Refresh()
    {

        ...
    }

在AMapPage.razor.js我们加载地图，并设置地图的中心点。和一些地图挂件。此外，我们还需要监听地图的中心点变化，更新中心点。 这些代码可以从官方示例中复制。(https://lbs.amap.com/demo/javascript-api-v2/example/map/map-moving)。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
console.info("start load")
window.viewService = {
    map: null,
    zoom: 13,
    amaplocation: [116.397428, 39.90923],
    SetAmapContainerSize: function (width, height) {
        console.info("setting container size")

        var div = document.getElementById("container");
        div.style.height = height + "px";

    },
    SetLocation: function (longitude, latitude) {
        console.info("setting loc", longitude, latitude)
        window.viewService.amaplocation = [longitude, latitude];
        if (window.viewService.map) {
            window.viewService.map.setZoomAndCenter(window.viewService.zoom, window.viewService.amaplocation);

            console.info("set loc", window.viewService.zoom, window.viewService.map)
        }
    },
    isHotspot: true

}
AMapLoader.load({ //首次调用 load
    key: '0896cedc056413f83ca0aee5b029c65d',//首次load key为必填
    version: '2.0',
    plugins: ['AMap.Scale', 'AMap.ToolBar', 'AMap.InfoWindow', 'AMap.PlaceSearch']
}).then((AMap) => {
    console.info("loading..")
    var opt = {
        resizeEnable: true,
        center: window.viewService.amaplocation,
        zoom: window.viewService.zoom,
        isHotspot: true
    }
    var map = new AMap.Map('container', opt);
    console.info(AMap, map, opt)

    map.addControl(new AMap.Scale())
    map.addControl(new AMap.ToolBar())
    window.viewService.marker = new AMap.Marker({
        position: map.getCenter()
    })
    map.add(window.viewService.marker);
    var placeSearch = new AMap.PlaceSearch();  //构造地点查询类
    var infoWindow = new AMap.InfoWindow({});
    map.on('hotspotover', function (result) {
        placeSearch.getDetails(result.id, function (status, result) {
            if (status === 'complete' && result.info === 'OK') {
                onPlaceSearch(result);
            }
        });
    });

    map.on('moveend', onMapMoveend);
    // map.on('zoomend', onMapMoveend);
    //回调函数

    window.viewService.map = map;

    function onMapMoveend() {
        var zoom = window.viewService.map.getZoom(); //获取当前地图级别
        var center = window.viewService.map.getCenter(); //获取当前地图中心位置
        if (window.viewService.marker) {
            window.viewService.marker.setPosition(center);

        }
        window.objRef.invokeMethodAsync('OnMapMoveend', center);


    }
    function onPlaceSearch(data) { //infoWindow.open(map, result.lnglat);
        var poiArr = data.poiList.pois;
        if (poiArr[0]) {
            var location = poiArr[0].location;
            infoWindow.setContent(createContent(poiArr[0]));
            infoWindow.open(window.viewService.map, location);
        }
    }
    function createContent(poi) {  //信息窗体内容
        var s = [];
        s.push('<div class="info-title">' + poi.name + '</div><div class="info-content">' + "地址：" + poi.address);
        s.push("电话：" + poi.tel);
        s.push("类型：" + poi.type);
        s.push('<div>');
        return s.join("<br>");
    }


    console.info("loaded")

}).catch((e) => {
    console.error(e);
});
window.initObjRef = function (objRef) {
    window.objRef = objRef;
}

地图中心点改变时，我们需要使用window.objRef.invokeMethodAsync('OnMapMoveend', center);从JS runtime中通知到C#代码。

同时，在AMapPage.razor中配置一个方法，用于接收从JS runtime发来的回调通知。
在此赋值CurrentLocation属性。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[JSInvokable]
public async Task OnMapMoveend(dynamic location)
{
    await Task.Run(() =>
     {
         var locationArray = JsonConvert.DeserializeObject<double[]>(location.ToString());
         MainPageViewModel.CurrentLocation=new Location.Location()
             {
                 Longitude=locationArray[0],
                 Latitude =locationArray[1]
             };
     });
}

同时监听CurrentLocation属性的值，一旦发生变化，则调用JS runtime中的viewService.SetLocation方法，更新地图中心点。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
protected override async Task OnInitializedAsync()
{
    MainPageViewModel.PropertyChanged +=  async (o, e) =>
    {
        if (e.PropertyName==nameof(MainPageViewModel.CurrentLocation))
        {
            if (MainPageViewModel.CurrentLocation!=null)
            {
                var longitude = MainPageViewModel.CurrentLocation.Longitude;
                var latitude = MainPageViewModel.CurrentLocation.Latitude;
                await JSRuntime.InvokeVoidAsync("viewService.SetLocation", longitude, latitude);
            }
        }


    };

}

在MainPageViewModel类中，我们添加一个PropertyChanged事件，用于监听CurrentLocation属性的改变。

当手指滑动地图触发位置变化，导致CurrentLocation属性改变时，将当前的中心点转换为具体的地址。这里使用了高德逆地理编码API服务（https://restapi.amap.com/v3/geocode/regeo）解析CurrentLocation的值， 还需使用了防抖策略，避免接口的频繁调用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

public MainPageViewModel()
{
    PropertyChanged+=MainPageViewModel_PropertyChanged;
    ...
}



private async void MainPageViewModel_PropertyChanged(object sender, System.ComponentModel.PropertyChangedEventArgs e)
{
    if (e.PropertyName == nameof(CurrentLocation))
    {
        if (CurrentLocation!=null)
        {

            // 使用防抖
            using (await asyncLock.LockAsync())
            {

                var amapLocation = new Location.Location()
                {
                    Latitude=CurrentLocation.Latitude,
                    Longitude=CurrentLocation.Longitude
                };
                var amapInverseHttpRequestParamter = new AmapInverseHttpRequestParamter()
                {
                    Locations= new Location.Location[] { amapLocation }
                };
                ReGeocodeLocation reGeocodeLocation = null;
                try
                {
                    reGeocodeLocation = await amapHttpRequestClient.InverseAsync(amapInverseHttpRequestParamter);
                }
                catch (Exception ex)
                {

                    Console.WriteLine(ex.ToString());
                }

                throttledAction.Update(() =>
                {
                    MainThread.BeginInvokeOnMainThread(() =>
                    {
                        CurrentLocation=amapLocation;
                        if (reGeocodeLocation!=null)
                        {
                            Address = reGeocodeLocation.Address;
                            Pois=new ObservableCollection<Poi>(reGeocodeLocation.Pois);

                        }
                    });
                });
                throttledAction.Invoke();
            }
        }
    }
}

至此我们完成了地图组件的基本功能。

创建交互逻辑

在MainPage.xaml中，创建一个选择器按钮，以及一个卡片模拟选择器按钮点击后的弹窗。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

<Button Clicked="Button_Clicked"
        Grid.Row="1"
        x:Name="SelectorButton"
        HorizontalOptions="Center"
        VerticalOptions="Center"
        Text="{Binding Address, TargetNullValue=请选择地点}"></Button>


<Border StrokeShape="RoundRectangle 10"
    Grid.RowSpan="2"
    x:Name="SelectorPopup"
    IsVisible="False"
    Margin="5,50"
    MinimumHeightRequest="500">

    <Grid Padding="0">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"></RowDefinition>
            <RowDefinition Height="Auto"></RowDefinition>
            <RowDefinition></RowDefinition>
        </Grid.RowDefinitions>

        <Grid Grid.Row="0">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*"></ColumnDefinition>
                <ColumnDefinition></ColumnDefinition>
            </Grid.ColumnDefinitions>
            <Label FontSize="Large"
                    Margin="10, 10, 10, 0"
                    FontAttributes="Bold"
                    Text="选择地点"></Label>
            <HorizontalStackLayout Grid.Column="1"
                                    HorizontalOptions="End">
                <Button Text="删除"
                        Margin="5,0"
                        Command="{Binding Remove}"></Button>
                <Button Text="完成"
                        Margin="5,0"
                        Command="{Binding Done}"></Button>
            </HorizontalStackLayout>
        </Grid>

        <Grid Grid.Row="1"
                Margin="10, 10, 10, 0">
            <Grid.RowDefinitions>
                <RowDefinition></RowDefinition>
                <RowDefinition Height="Auto"></RowDefinition>
            </Grid.RowDefinitions>
            <Label HorizontalTextAlignment="Center"
                    VerticalOptions="Center"
                    x:Name="ContentLabel"
                    Text="{Binding Address}"></Label>
            <Border IsVisible="False"
                    Grid.RowSpan="2"
                    x:Name="ContentFrame">
                <Entry Text="{Binding Address, Mode=TwoWay}"
                        Placeholder="请输入地址, 按Enter键完成"
                        Completed="Entry_Completed"
                        Unfocused="Entry_Unfocused"
                        ClearButtonVisibility="WhileEditing"></Entry>
            </Border>
            <Border x:Name="ContentButton"
                    Grid.Row="1"
                    HorizontalOptions="Center"
                    VerticalOptions="Center">
                <Label>
                    <Label.FormattedText>
                        <FormattedString>
                            <Span FontFamily="FontAwesome"
                                    Text="&#xf044;"></Span>
                            <Span Text=" 修改"></Span>
                        </FormattedString>
                    </Label.FormattedText>

                </Label>
                <Border.GestureRecognizers>
                    <TapGestureRecognizer Tapped="TapGestureRecognizer_Tapped">
                    </TapGestureRecognizer>
                </Border.GestureRecognizers>
            </Border>
        </Grid>
        <BlazorWebView Grid.Row="2"
                        Margin="-10, 0"
                        x:Name="mainMapBlazorWebView"
                        HostPage="wwwroot/amap_index.html">
            <BlazorWebView.RootComponents>
                <RootComponent Selector="#app"
                                x:Name="rootComponent"
                                ComponentType="{x:Type views:AMapPage}" />
            </BlazorWebView.RootComponents>
        </BlazorWebView>
    </Grid>
</Border>

最终效果如下：

项目地址

Github:maui-samples

]]> 地图组件在手机App中常用地理相关业务，如查看线下门店，设置导航，或选取地址等。是一个较为常见的组件。在.NET MAUI 中，有两种方案可以集成高德地图，一种是使用原生库绑定。但这种方案需要大量平台原生开发的知识，而且需要对每一个平台进行适配。在这里我介绍第二种方案：.NET MAUI Blazor + 高德地图JS API 2.0 库的实现。JS API 2.0 是高德开放平台基于WebGL的地图组件，可以将高德地图模块集成到.NET MAUI Blazor中的BlazorWebView控件。 [.NET项目实战] Elsa开源工作流组件应用（三）：实战演练 https://blog.matoapp.net/posts/6af59036/ 2024-03-21T15:58:00.000Z 2025-09-24T16:30:02.362Z

补充

之前的文章简单介绍了工作流和Elsa工作流库，这里再补充说明两点

  1. 工作流的使用场景非常广泛，几乎涵盖了所有需要进行业务流程自动化管理的领域。

  2. 学习一个开源库，最简单的方法就是看源码，Elsa的工作流引擎源码非常简单易懂，并且提供了非常丰富的示例代码，举一个例子：审批工作流示例.\src\samples\aspnet\Elsa.Samples.AspNet.DocumentApproval


这个审批流是这样的：
作者发来一个文章，有两个审批人需要全部审批通过，文章才算通过，否则退回。

我们尝试阅读工作流源代码DocumentApprovalWorkflow.cs，并运行此项目，用postman发送请求

第一步：

假设这名叫Amanda的作者要发布文章，请求发送后，作者浏览器显示发送成功稍安勿躁之类的提示

同时后台打印作者信息和4个链接，分别是Jack和Lucy两位审批人“通过”和“退回”的url链接

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Activities =
{
    new HttpEndpoint
    {
        Path = new("/documents"),
        SupportedMethods = new(new[] { HttpMethods.Post }),
        ParsedContent = new(documentVariable),
        CanStartWorkflow = true
    },
    new WriteLine(context => $"Document received from {documentVariable.Get<dynamic>(context)!.Author.Name}."),
    new WriteHttpResponse
    {
        Content = new("<h1>Request for Approval Sent</h1><p>Your document has been received and will be reviewed shortly.</p>"),
        ContentType = new(MediaTypeNames.Text.Html),
        StatusCode = new(HttpStatusCode.OK),
        ResponseHeaders = new(new HttpHeaders { ["X-Powered-By"] = new[] { "Elsa 3.0" } })
    },

第二步：

Jack觉得文章不错，通过浏览器请求了“通过”链接，而Lucy觉得文章还不够好，需改进，她在浏览器中请求了“退回”链接。

两位审批人的审批结果存储于approvedVariable变量中

同时他们的浏览器返回的响应内容：Thanks for the approval 或 Sorry to hear that

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
new Fork
{
    JoinMode = ForkJoinMode.WaitAll,
    Branches =
    {
        // Jack
        new Sequence
        {
            Activities =
            {
                new WriteLine(context => $"Jack approve url: \n {GenerateSignalUrl(context, "Approve:Jack")}"),
                new WriteLine(context => $"Jack reject url: \n {GenerateSignalUrl(context, "Reject:Jack")}"),
                new Fork
                {
                    JoinMode = ForkJoinMode.WaitAny,
                    Branches =
                    {
                        // Approve
                        new Sequence
                        {
                            Activities =
                            {
                                new Event("Approve:Jack"),
                                new SetVariable
                                {
                                    Variable = approvedVariable,
                                    Value = new(true)
                                },
                                new WriteHttpResponse
                                {
                                    Content = new("Thanks for the approval, Jack!"),
                                }
                            }
                        },

                        // Reject
                        new Sequence
                        {
                            Activities =
                            {
                                new Event("Reject:Jack"),
                                new SetVariable
                                {
                                    Variable = approvedVariable,
                                    Value = new(false)
                                },
                                new WriteHttpResponse
                                {
                                    Content = new("Sorry to hear that, Jack!"),
                                }
                            }
                        }
                    }
                }
            }
        },

        // Lucy
        new Sequence
        {
            Activities =
            {
                new WriteLine(context => $"Lucy approve url: \n {GenerateSignalUrl(context, "Approve:Lucy")}"),
                new WriteLine(context => $"Lucy reject url: \n {GenerateSignalUrl(context, "Reject:Lucy")}"),
                new Fork
                {
                    JoinMode = ForkJoinMode.WaitAny,
                    Branches =
                    {
                        // Approve
                        new Sequence
                        {
                            Activities =
                            {
                                new Event("Approve:Lucy"),
                                new SetVariable
                                {
                                    Variable = approvedVariable,
                                    Value = new(true)
                                },
                                new WriteHttpResponse
                                {
                                    Content = new("Thanks for the approval, Lucy!"),
                                }
                            }
                        },

                        // Reject
                        new Sequence
                        {
                            Activities =
                            {
                                new Event("Reject:Lucy"),
                                new SetVariable
                                {
                                    Variable = approvedVariable,
                                    Value = new(false)
                                },
                                new WriteHttpResponse
                                {
                                    Content = new("Sorry to hear that, Lucy!"),
                                }
                            }
                        }
                    }
                }
            }
        }
    }
},

第三步：

根据approvedVariable变量判定文章是否被审核通过。

如果通过则在控制台打印Document document-1 approved!, 否则打印Document document-1 rejected!

1
2
3
4
5
6
7
8
    new WriteLine(context => $"Approved: {approvedVariable.Get<bool>(context)}"),
    new If(context => approvedVariable.Get<bool>(context))
    {
        Then = new WriteLine(context => $"Document ${documentVariable.Get<dynamic>(context)!.Id} approved!"),
        Else = new WriteLine(context => $"Document ${documentVariable.Get<dynamic>(context)!.Id} rejected!")
    }
}

Elsa工作流源码还提供了大量的Sample，这里就不一一列举了，

需求描述

根据不同的时间规则，发送下发问卷给客户填写。

下发问卷给用户填写，且填写有超时时间，期间要提醒用户答题，

如果问卷未在规定的时间内作答则，则作废，并提醒用户。

需求分析

我们将需求尽可能分解成为单一职责的功能单元，并定义这些功能单元的输入输出。

下发问卷任务 PublishQuestionnaireActivity

下发问卷是将问卷（Questionnaire）实例化成问卷实例（Survey），问卷实例绑定用户Id，用户在问卷实例上作答。明确输入和输出：

  • 输入：问卷ID
  • 输出：问卷实例对象SurveyDto

通知任务 NotificationActivity

通知在这个需求中需要发送问卷状态，时间等内容给对应的用户，同通至少包含标题和内容。

  • 输入：标题和内容
  • 输出：无

问卷状态跟踪任务 WaitFillInSurveyActivity

这个任务要追踪问卷实例的状态，当问卷实例状态为已完成时，可以继续执行后续任务。

  • 输入：问卷实例ID
  • 输出：无

定时和延时任务

用于延时执行每个下发问卷的时间，等待问卷超时，以及延时发送通知等。

  • 输入：开始日期，延时日期，间隔时间或cron表达式
  • 输出：无

根任务

根任务包含所有的子任务，完成这个任务后，整个流程结束。在这个需求中根任务只需要知道将什么问卷，发送给哪位用户，以及在何时发送这三个问题。

  • 输入：问卷ID，用户ID，发送时间
  • 输出：无

各子任务参数对于他们的根任务是透明的（Invisible），根任务只需要关心是否完成，而不需要知道任务参数。

代码实现

下发问卷活动 PublishQuestionnaireActivity

下发问卷任务可以抽象成为下发问卷活动 PublishQuestionnaireActivity
创建PublishQuestionnaireActivity类并设置输入QuestionnaireId，输出SurveyDto

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class PublishQuestionnaireActivity : Activity<SurveyDto>
{
    public PublishQuestionnaireActivity()
    {

    }
    public PublishQuestionnaireActivity(long questionnaireId)
    {
        QuestionnaireId = new Input<long>(questionnaireId);
    }


    
    public Input<long> QuestionnaireId { get; set; } = default!;
}


重写ExecuteAsync方法，完成问卷下发逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
protected override async ValueTask ExecuteAsync(ActivityExecutionContext context)
{
    var _surveyAppService = context.GetRequiredService<ISurveyAppService>();
    if (_surveyAppService != null)
    {
        var currentUserId = await context.GetInputValueAsync<Guid>("UserId");
        var survey = await _surveyAppService.PublishAsync(new PublishInput()
        {
            QuestionnaireId = this.QuestionnaireId.Get<long>(context),
            UserId = currentUserId

        }) ?? throw new Exception("创建问卷失败");
        context.SetResult(survey);
    }


    await context.CompleteActivityAsync();

}

如此，其他的任务分别抽象成为相应的活动，这里展示完整代码

通知活动：NotificationActivity

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
public class NotificationActivity : Activity
{


    public NotificationActivity()
    {

    }
    public NotificationActivity(string title, string content)
    {
        Content = new Input<string>(content);
        Title = new Input<string>(title);
    }

    protected override async ValueTask ExecuteAsync(ActivityExecutionContext context)
    {
        var notificationManager = context.GetRequiredService<NotificationManager>();

        if (notificationManager != null)
        {
            var title = this.Title.Get(context);
            var content = this.Content.Get(context);
            var currentUserId = await context.GetInputValueAsync<Guid>("UserId");
            var data = new CreatePrivateMessageNotificationEto(currentUserId, title, content);
            await notificationManager.Send(data);
        }


    await context.CompleteActivityAsync();

}

    public Input<string> Title { get; set; } = default!;
    public Input<string> Content { get; set; } = default!;
}

等待问卷完成活动：WaitFillInSurveyActivity

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
public class WaitFillInSurveyActivity : Activity
{
    public WaitFillInSurveyActivity()
    {

    }
    public WaitFillInSurveyActivity(Func<ExpressionExecutionContext, long?> surveyId)
: this(Expression.DelegateExpression(surveyId))
    {
    }

    public WaitFillInSurveyActivity(long surveyId) => SurveyId = new Input<long>(surveyId);

    public WaitFillInSurveyActivity(Expression expression) => SurveyId = new Input<long>(expression, new MemoryBlockReference());


    /// <inheritdoc />
    protected override ValueTask ExecuteAsync(ActivityExecutionContext context)
    {
        var surveyId = SurveyId.Get(context);
        if (surveyId == default)
        {
            var survey = context.ExpressionExecutionContext.GetLastResult<SurveyDto>();
            surveyId = survey.Id;
        }
        var payload = new WaitFillInSurveyBookmarkPayload(surveyId);
        context.CreateBookmark(new CreateBookmarkArgs
        {
            Payload = payload,
            Callback = Resume,
            BookmarkName = Type,
            IncludeActivityInstanceId = false
        });
        return ValueTask.CompletedTask;
    }

    private async ValueTask Resume(ActivityExecutionContext context)
    {
        await context.CompleteActivityAsync();
    }

    public Input<long> SurveyId { get; set; } = default!;
}

此任务需要等待，我们创建一个Bookmark，注意创建Bookmark时，我们根据问卷实例SurveyId判断是否完成问卷的回答，因此指定IncludeActivityInstanceId为false，创建携带SurveyId的Payload类型：

1
2
public record WaitFillInSurveyBookmarkPayload(long SurveyId);

在回调OnResumeAsync中，我们使用context.CompleteActivityAsync来完成任务。

定时和延时活动：

Elsa.Scheduling库提供了用于定时和延时任务的触发器（触发器属于工作流的一种）

在[.NET项目实战] Elsa开源工作流组件应用（二）：内核解读 一文 “构建 - 构建活动 “章节 列出了Elsa所有内建的活动。

这里使用Elsa内建的三个触发器：

StartAt 在未来特定的时间戳触发工作流触发器
Delay 延迟执行工作流触发器。
Timer 定期触发工作流触发器。

问卷活动：QuestionnaireActivity

问卷活动是下发问卷，通知，等待填写问卷等活动的父级。

Elsa定义了容器类型的活动Container类型，其中的Activities可以包含其他活动。

Sequence和Parallel都是容器类型，是Activity的子类，它们分别表示并行和顺序执行。

除此之外我们还需要两个内建活动：

Fork：分支，用于分支并行执行，与Parallel类似，但比它多了一个等待完成功能。

通过ForkJoinMode属性，可以指定分支任务的执行方式，ForkJoinMode.WaitAny：等待任意一个任务完成，ForkJoinMode.WaitAll：等待所有任务完成。

Fault：故障，用于在工作流执行过程中，遇到异常时，触发故障。并结束工作流。

创建问卷活动类型QuestionnaireActivity，继承自Sequence类型，并设置一些属性，如问卷Id，问卷填写超时时间等。

[可选]Elsa在注册工作流时，Activity对象是会被序列化并存储到WorflowDefinition表中的， 因此这些属性可以被持久化到数据库中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class QuestionnaireActivity : Sequence
{
    //可选，用于持久化一些属性
    public TimeSpan Delay { get; set; }
    public DateTime StartAt { get; set; }
    public TimeSpan Interval { get; set; }
    public string Cron { get; set; }
    public TimeSpan Duration { get; set; }
    public long QuestionnaireId { get; set; }
    public TimeSpan FillInTimeout { get; set; } = TimeSpan.FromHours(2);

    public QuestionnaireActivity()
    {

    }   
}

重写构造函数，并设置Activities属性

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
public QuestionnaireActivity(long questionnaireId, TimeSpan fillInTimeout)
{
    this.QuestionnaireId = questionnaireId;
    this.FillInTimeout = fillInTimeout;
    var currentSurvey = new Variable<SurveyDto>();
    Variables.Add(currentSurvey);
    Activities = new List<IActivity>()
    {
        //流程开始打印
        new WriteLine("问卷流程开始"),

        //下发问卷任务
        new PublishQuestionnaireActivity(QuestionnaireId)
        {
            Name="PublishQuestionnaire",
            Result=new Output<Questionnaire.Survey.Dto.SurveyDto> (currentSurvey)
        },
        //问卷到达提醒             
        new NotificationActivity("新问卷提醒", "您有新的问卷，请查收"),

        //问卷处理分支 
        new Fork
        {
            JoinMode = ForkJoinMode.WaitAny,
            Branches =
            {
                //问卷即将过期提醒 
                new Sequence
                {
                    Activities =
                    {
                        //等待
                        new Delay
                        {
                            Name = "RemindDelay",
                            TimeSpan = new(RemindDelay)
                        },
                        //通知
                        new NotificationActivity("问卷即将超时", "问卷即将超时，请尽快回答")
                    }
                },
                //问卷过期处理以及提醒 
                new Sequence
                {
                    Activities =
                    {
                        //等待
                        new Delay
                        {
                            Name = "TimeoutDelay",
                            TimeSpan = new(FillInTimeout)
                        },
                        //通知
                        new NotificationActivity("问卷已过期", "问卷已过期，请等待工作人员处理"),

                        //处理
                        new Fault()
                        {
                            Message=new ("问卷回答超时")
                        }
                    }
                },
                //问卷状态跟踪 
                new Sequence
                {
                    Activities =
                    {
                        new WriteLine("开始等待问卷提交信号"),
                        new WaitFillInSurveyActivity(context => currentSurvey.Get<SurveyDto>(context)?.Id)

                    }
                }
            }
        },
        //流程结束打印 
        new WriteLine("完成流程结束"),
        new Finish(),
    };
}

创建工作流

现在我们来创建测试工作流，

  1. 添加一个工作流参数UserId，用于各活动中对用户的查询依赖。
  2. 分别实现4个并行任务：延时发送问卷，定时发送问卷，定期间隔发送问卷，根据Cron表达式执行。和一个串行任务
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
public class Test1Workflow : WorkflowBase
{
    public Guid UserId { get; set; }
    protected override void Build(IWorkflowBuilder workflow)
    {
        var startTime = new Variable<DateTimeOffset>();
        workflow.Inputs.Add(
                    new InputDefinition() { Name = "UserId", Type = typeof(Guid), StorageDriverType = typeof(WorkflowStorageDriver) }
            );
        workflow.WithVariable(startTime);

        workflow.Root = new Sequence
        {
            Activities =
                {
                    new WriteLine("Start"),
                    new SetVariable<DateTimeOffset>
                    {
                        Variable = startTime,
                        Value = new (DateTime.Now )
                    },
                    
                    new Parallel()
                    {
                        Activities =
                        {
                            //并行任务1：延时发送问卷
                            new Sequence()
                            {
                                Activities =
                                {
                                    //问卷1 将在工作流启动后1小时执行

                                    new Delay(TimeSpan.FromHours(1)),
                                    new QuestionnaireActivity(1),
                                }
                            },
                            //并行任务2：定时发送问卷
                            new Sequence()
                            {
                                Activities =
                                {
                                    //问卷2 将在 2024-4-1 08:30:00 执行
                                    new StartAt(new DateTime(2024,4,1,8,30,0)),
                                    new Delay(TimeSpan.FromHours(2)),
                                    new QuestionnaireActivity(2),
                                }
                            },
                            //并行任务3：定期间隔发送问卷
                            new Sequence()
                            {
                                Activities =
                                {
                                    //问卷3 每隔两个小时执行
                                    new Timer(new TimeSpan(2,0,0)),

                                    new Delay(TimeSpan.FromHours(2)),
                                    new QuestionnaireActivity(3),
                                }
                            },
                            //并行任务4：根据Cron表达式执行
                            new Sequence()
                            {
                                Activities =
                                {
                                    //问卷4 每个月的最后一天上午10点执行任务
                                    new Cron(cronExpression:"0 0 10 L * ?"),

                                    new Delay(TimeSpan.FromHours(2)),
                                    new QuestionnaireActivity(4),
                                }
                            },
                            //并行任务5：根据某时间发送问卷
                            new Sequence()
                            {
                                Activities =
                                {
                                    new StartAt(context=> startTime.Get(context).AddMinutes(90)),

                                    new Delay(TimeSpan.FromHours(2)),
                                    new QuestionnaireActivity(5),
                                }
                            },



                            //串行任务
                            new Sequence()
                            {
                                Activities =
                                {
                                    //问卷3 将在工作流启动后2小时执行

                                    new Delay(TimeSpan.FromHours(2)),
                                    new QuestionnaireActivity(3),

                                        //问卷4 将在问卷3完成1天后执行

                                    new Delay(TimeSpan.FromDays(1)),
                                    new QuestionnaireActivity(4),

                                    //问卷5 将在问卷4完成3天后执行

                                    new Delay(TimeSpan.FromDays(3)),
                                    new QuestionnaireActivity(5),
                                }
                            }
                        }
                    },
                    new Finish(),
            },
        };
    }
}

开始工作流

工作流启动参数需设置Input对象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

var input = new Dictionary<string, object>
{

    {"UserId", "D1522DBC-5BFC-6173-EB60-3A114454350C"},

};

var startWorkflowOptions = new StartWorkflowRuntimeOptions
{
    Input = input,
    VersionOptions = versionOptions,
    InstanceId = instanceId,
};


// Start the workflow.
var result = await _workflowRuntime.StartWorkflowAsync(workflowDefinition.DefinitionId, startWorkflowOptions);

下面进入喜闻乐见的踩坑填坑环节

TroubleShooting

  1. 在活动中执行异步操作时，会导致报错：

    如下面的代码，执行Excute方法中的 context.CompleteActivityAsync()方法，时报错

原因分析：scope资源被提前释放

代码先执行到了112行，scope释放

解决：带有异步的操作一定要使用ExecuteAsync方法

  1. delay之后，Workflow的Input无法访问

原因分析：

Delay或其他Schedule类型的Activity，通过创建Bookmark挂起任务，当任务被唤醒时，input被workflowState.Output替换掉，和原先的input不一样了。

解决：

虽然input被替换了，但数据库的input还在，可以通过workflowInstanceId先取回workflowInstance对象，再通过instance.WorkflowState.Input.TryGetValue方法获取原始input值。

可以创建一个一个扩展方法GetInputValueAsync，Delay之后的活动中调用即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public static async Task<TValue> GetInputValueAsync<TValue>(this ActivityExecutionContext context, string name)
{
    TValue value;
    if (!context.TryGetWorkflowInput(name, out value))
    {
        var workflowInstanceStore = context.GetRequiredService<IWorkflowInstanceStore>();

        var instance = await workflowInstanceStore.FindAsync(new WorkflowInstanceFilter()
        {
            Id = context.WorkflowExecutionContext.Id

        });
        if (instance != null)
        {
            instance.WorkflowState.Input.TryGetValue(name, out value);
        }
    }

    return value;


}

在Activity中调用：

1
await context.GetInputValueAsync<Guid>("UserId");

持续更新中…

–完结–

]]> 之前的文章简单介绍了工作流和Elsa工作流库，这里再补充说明两点工作流的使用场景非常广泛，几乎涵盖了所有需要进行业务流程自动化管理的领域。学习一个开源库，最简单的方法就是看源码，Elsa的工作流引擎源码非常简单易懂，并且提供了非常丰富的示例代码，举一个例子：审批工作流示例这个审批流是这样的：作者发来一个文章，有两个审批人需要全部审批通过，文章才算通过，否则退回。 [.NET项目实战] Elsa开源工作流组件应用（二）：内核解读 https://blog.matoapp.net/posts/d5b810ff/ 2024-03-20T11:53:00.000Z 2025-09-24T16:30:02.366Z

本篇将带你深入分析Elsa工作流原理，排除干扰展示关键代码段，以加深理解

定义

变量

Elsa工作原理可以抽象理解为管道中间件 + 异步模型

Elsa中，活动的变量的获取和设置都是异步的。Elsa定义了Variable类型作为异步操作的结果或者说是异步操作的占位符，这个变量在运行的时候才会填充数值。这与我们熟悉C#中的Task，或者js里的promise对象作用相同。输入Input，OutPut都属于 Variable。

Elsa模拟了内存寄存器（MemoryRegister）以及Set和Get访问器实现异步模型。

内存寄存器类

1
2
3
4
5
6
public class MemoryRegister
{
    ...
    public IDictionary<string, MemoryBlock> Blocks { get; }
    
}

寄存器中的存储区块类

1
2
3
4
5
6
7
8
9
10
11
12
13
public class MemoryBlock
{
    ...
    /// <summary>
    /// The value stored in this block.
    /// </summary>
    public object? Value { get; set; }
    
    /// <summary>
    /// Optional metadata about this block.
    /// </summary>
    public object? Metadata { get; set; }
}

变量到存储的映射类

Id可以代表变量在内存区块中的引用地址

1
2
3
4
5
6
7
8
9
10
11
public class MemoryBlockReference
{
    
    /// <summary>
    /// The ID of the memory block.
    /// </summary>
    public string Id { get; set; } = default!;

    public object? Get(MemoryRegister memoryRegister) => GetBlock(memoryRegister).Value;
}

构建活动时将创建活动中变量到存储区块的映射，分配一个引用给变量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public void AssignInputOutputs(IActivity activity)
{
    var activityDescriptor = _activityRegistry.Find(activity.Type, activity.Version) ?? throw new Exception("Activity descriptor not found");
    var inputs = activityDescriptor.GetWrappedInputProperties(activity).Values.Cast<Input>().ToList();
    var seed = 0;

    foreach (var input in inputs)
    {
        var blockReference = input?.MemoryBlockReference();

        if (blockReference != null!)
            if (string.IsNullOrEmpty(blockReference.Id))
                blockReference.Id = $"{activity.Id}:input-{seed}";

        seed++;
    }
   ...
}

异步变量获取和设置：

可以通过上下文对象的Set，和Get方法，异步获取和设置异步变量。

上下文对象

查看源码可以看到Elsa定义了如下Context

其中比较重要的上下文对象：

活动上下文（ActivityExecutionContext）

活动上下文对象由Elsa.Runtime提供，在工作流执行函数中可供访问。通过它可访问包含活动实例、当前输入和输出等。通过它可以访问当前活动所在的工作流执行上下文。

工作流执行上下文（WorkflowExecutionContext）

工作流上下文对象由Elsa.Runtime提供，可通过活动上下文（ActivityExecutionContext）访问其所属工作流执行上下文。通过它可访问包含工作流实例、当前活动、当前输入和输出等。

表达式执行上下文（ExpressionExecutionContext）

表达式执行上下文用于在构建活动时传递内存变量（输入，输出），其中包含MemoryRegister对象。

通过表达式执行上下文（ExpressionExecutionContext）获取到变量的值：

构建

构建活动

Elsa默认帮我们建立了这些活动：

他们都实现了IActivity接口，Activity和CodeActivity是IActivity的实现类，对应的是一个空的活动，（CodeActivity是带有自动完成功能的空活动）

我们要做的是继承这个活动，重写Execute方法以实现我们自己的业务。比如：

1
2
3
4
5
6
7
8
public class HelloWorld : Activity
{
    protected override async ValueTask ExecuteAsync(ActivityExecutionContext context)
    {
        Console.WriteLine("Hello World!");
        await CompleteAsync();
    }
}

以官方默认的WiteLine为例，这个类的Execute代码如下：

1
2
3
4
5
6
7
protected override void Execute(ActivityExecutionContext context)
{
    var text = context.Get(Text);
    var provider = context.GetService<IStandardOutStreamProvider>() ?? new StandardOutStreamProvider(System.Console.Out);
    var textWriter = provider.GetTextWriter();
    textWriter.WriteLine(text);
}

构建工作流

首要目标是拿到一个工作流对象（Workflow），Elsa启动时会从工作流提供者（IWorkflowProvider）获取所有能用的工作流。并注册到资源池中

1
2
3
4
5
6
public interface IWorkflowProvider
{
    string Name { get; }

    ValueTask<IEnumerable<MaterializedWorkflow>> GetWorkflowsAsync(CancellationToken cancellationToken = default);
}

Elsa默认的实现类是如下两种，BlobStorageWorkflowProvider将从数据库（BlobStorage）中反序列化来注册。ClrWorkflowProvider使用工作流构建器注册。

我们先定义工作流描述类，它继承自IWorkflow, WorkflowBase是IWorkflow的抽象基类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
class SequentialWorkflow : WorkflowBase
{
    protected override void Build(IWorkflowBuilder workflow)
    {
        workflow.Root = new Sequence
        {
            Activities =
            {
                new WriteLine("Line 1"),
                new WriteLine("Line 2"),
                new WriteLine("Line 3")
            }
        };
    }
}

Elsa初始化时，WorkflowBuilder会构建程序集中所有实现IWorkflow的类。

WorkflowBuilder中的BuildWorkflowAsync方法会将工作流描述类IWorkflow对象构建成Workflow对象。

这里思考一个问题：终执行的代码是在活动中定义的，但为什么返回的是Workflow对象？通过代码研读，实际上Workflow也是一个IActivity活动，只不过它具有一个Root根节点的复合活动。活动的定义请参考官方文档

BuildWorkflowAsync中的具体实现如下：

运行

注册

注册包括注册工作流和注册活动，配置Elsa时需要使用如下两个方法：

1
2
.AddActivitiesFrom<Program>()
.AddWorkflowsFrom<Program>()

注册工作流

工作流可以通过ClrWorkflowProvider，使用工作流构建器注册，也可以从本地存储（BlobStorage）中反序列化来注册。
代码构建的工作流是通过实现IWorkflow接口，在Elsa初始化时将工作流注册到工作流定义持久化到数据库的WorkflowDefinition表中

通过工作流构建器注册：

注册活动

Elsa使用描述器（IActivityDescriber）提供一个描述符(ActivityDescriptor)，这里比较绕，阅读源码可以发现，其实是通过各种反射获取活动派生类的特征数据（有的系统喜欢将称之为元数据），封装这些数据的类型称之为描述符，特征数据可以作为在界面上显示，分组，排序的信息。

活动不同于工作流，它在运行中不持久化于数据库，而是以注册表的形式存储于内存中。

1
IDictionary<(string Type, int Version), ActivityDescriptor> _activityDescriptors

在构建工作流的时候自动注册活动，也可以通过实现IActivity接口，在Elsa初始化时将所有活动注册到注册表中

Elsa启动时将所有实现了IActivity接口的类型注册为活动：

填充

启动时填充活动注册表和工作流定义表。
官方也给出了说明，各填充两次确保活动注册表和工作流定义表都是最新的：

阶段一：填充活动注册表
因为工作流定义可以用作活动，需要确保在填充工作流定义表之前填充活动注册表。

阶段二：填充工作流定义表

阶段三：重新填充活动注册表
填充了工作流定义表之后，我们需要重新填充活动注册表，以确保活动描述符是最新的。

阶段四：用当前的活动集重新更新工作流定义表。
最后，需要重新填充工作流定义表，以确保工作流定义是最新的。

Invoke活动

Elsa默认的管道中间件：

Elsa注册执行活动的中间件（DefaultActivityInvokerMiddleware）：

1
2
3
4
5
6
7
public static class ActivityInvokerMiddlewareExtensions
{
    /// <summary>
    /// Adds the <see cref="DefaultActivityInvokerMiddleware"/> component to the pipeline.
    /// </summary>
    public static IActivityExecutionPipelineBuilder UseDefaultActivityInvoker(this IActivityExecutionPipelineBuilder pipelineBuilder) => pipelineBuilder.UseMiddleware<DefaultActivityInvokerMiddleware>();
}

在执行活动的中间件（DefaultActivityInvokerMiddleware），最终活动被调用的代码如下：

可以看见，Elsa最终以反射的方式创建一个Activity实例，然后调用它的ExecuteAsync方法。

可观测性

设计器与APIs

实际上，Elsa的运行时和设计器是完全分离的。Elsa提供了一个基于Blazor的设计工具，它作为独立的项目发布在Github上： Elsa-Studio

因为和接口交互是通过REST API实现的，所以你也可以使用任何你想要的客户端来实现。

接设计器默认的HTTP API实现在Elsa.Workflows.Api库中，用于支持设计器的增删改查业务。

如果仅要使用工作流引擎，可以使用Elsa.Workflows.Management库，它只包含对于工作流的管理而不涉及HTTP接口。

工作流配置

打开设计器，点击“工作流（Workflow）”菜单，然后单击“定义（Definition）”选项卡。可以看到一个工作流定义的列表。点击右上角新增按钮，

在打开的页面中，拖拽活动到工作流图上，然后单击“保存（Save）”按钮。

在浏览器的网络请求中可以看到一个POST请求，请求地址为/workflow/definitions，请求参数为JSON格式，后端服务中WorkflowDefinitions的Endpoint中将对编辑器的“保存”请求进行处理

在请求负载中，WorkflowDefinitionModel字段会包含工作流定义和Root活动。

默认实现会将工作流定义和根活动序列化为JSON，并将其保存到数据库中。其中根活动在数据库WorkflowDefinition表的StringData列中存储。

当工作流执行时，Elsa会实例化（Materialize）Workflow对象


其中RootActivity会反序列化，可以看到StringData会被反序列化为IActivity对象

查看工作流状态

Elsa定义了不同的接口和数据库

主要的接口如下：

workflowDefinition：工作流定义接口，数据来自WorkflowDefinition表
workflowInstance：工作流实例接口，数据来自WorkflowInstance表
activity-execution：活动执行接口，查询活动的Id、状态以及结果，输入输出等上下文数据，数据主要通过查询ActivityExecutionRecords表来获取。
journal: 活动执行日志，数据来自WorkflowExecutionLogRecords表

打开设计器，点击“工作流（Workflow）”菜单，然后单击“实例（Instance）”选项卡。可以看到一个工作实例列表

点击条目即可查看工作流的执行日志和各活动的执行信息。Web页面中各片区的数据来源分布大致如下：

其中页面中央的工作流编辑器显示了工作流的结构，结合工作流的执行日志，可以直观的看到工作流的执行情况。可观测到执行的步骤，以及执行的耗时。

–完结–

]]> Elsa工作原理可以抽象理解为管道中间件 + 异步模型Elsa中，活动的变量的获取和设置都是异步的。Elsa定义了Variable类型作为异步操作的结果或者说是异步操作的占位符，这个变量在运行的时候才会填充数值。这与我们熟悉C#中的Task，或者js里的promise对象作用相同。输入Input，OutPut都属于 Variable。Elsa模拟了内存寄存器（MemoryRegister）以及Set和Get访问器实现异步模型。 深度观察2024中国系统架构师大会（SACC） https://blog.matoapp.net/posts/a3da18a9/ 2024-03-19T14:34:00.000Z 2025-09-24T16:30:02.738Z 今年的中国系统架构师大会（SACC）在我所在的城市广州举办，很荣幸受邀参加。这次能接触到国内最优秀的架构师，学习他们的架构思想和行业经验。对我而言非常有意义。

大会分为上下午共4场，我参加了上午的多云多活架构设计专场和下午的AIGC专场。

本篇文章就多云多活架构设计专场，我选取几位老师的观点进行分享。（我并不是架构师，只是对架构感兴趣，如有错误，还请指正）

张晓辉 Flomesh 高级云原生架构师

张老师分享了混合多云架构的技术方案，这里可以体现一个企业在技术层面发展到什么样的程度，根据这张图可以看看企业架构的复杂程度。可能大部分企业还在容器化，分布式架构和单一集群的复杂程度。

在资源抽象层面，利用统一的K8s Api，可以实现不同云厂商的资源抽象，实现资源的复用。K8s多集群可以作为防腐层，屏蔽基础设施层差异，避免厂商锁定

李中原 （平安银行股份有限公司 国产数据库技术负责人 ）

银行系统的技术架构需要满足高吞吐、低延迟要求，业务可靠性的要求，以及数据安全性的要求，同时，基于监管和法规的要求，技术架构需要自主可控。

李老师分享了银行架构的“去IOE化”的变迁。

对于可靠性要求，从传统的不能容许服务中断，逐渐过渡到允许服务中断但必须迅速恢复。

黄奕青 （腾讯云 技术专家）

黄老师对两位讲师做了补充，着重对异地多活架构中的问题，以及解决方案和设计要点等“三阶六要点”进行了分享。

  1. 技术架构的三个阶段：
  • 第一阶段是对业务需求的解读：一个是传统的需求分析，一个是企业聘请领域专家对需求建模
  • 第二阶段是确立架构，目前较为合理的架构是标准的微服务架构，已经被广泛应用（两地三中心架构）。
  • 第三阶段是在微服务架构之上构建单元化，该阶段需要解决如下异地多活架构中的挑战。
  1. 异地多活架构的挑战：
  • 因为网络基础设施的物理局限性，需要考虑异地资源使用时的延迟问题。
  • 数据访问效率问题：跨地域的数据访问速度慢会导致核心交易延迟，需要考虑数据切分和流量闭环治理。
  • 分布式事务成本问题：跨地域的分布式事务会带来高成本和复杂性。
  • 中间件的单元化考虑：在异地架构中，需要考虑中间件的单元化和调度。
  1. 六大设计要点：
  • 数据切分：设计大型分布式系统时首先要考虑数据如何切分。 数据按什么维度切分最合适，(如按客户号，还是哈希，按range范围？)
  • 流量闭环与单元化架构：黄老师强调了流量闭环的重要性，特别是在单元化架构中。这意味着流量需要在特定的单元内部循环，而不是跨单元流动，以减少无效的横向流量。为了实现这一目标，网关需要具有状态感知能力，能够识别客户信息并将流量路由到正确的单元。此外，单元和上层计算资源之间的逻辑绑定也是关键。
  • 中间件单元化：在单元化架构中，中间件（如MQ、Redis等）的链路也需要考虑单元化。特别是在跨单元的场景下，如客户之间的转账，会涉及到分布式事务的问题。这种分布式事务的调度和管理在异地多活架构下会被放大，成为实现的难点。
  • 数据切分与聚合查询：数据被切分到多个库后，聚合查询变得困难。黄老师提到了从前在一个库下可以轻松进行多表的聚合查询，但现在需要访问多个库进行查询。这需要对现有的查询策略和技术进行重新的设计和优化。
  • 业务连续性保障：单元之间的互备和业务连续性保障是必要的。
  • 分布式运维：针对大型核心系统的分布式运维需要特别关注。

戴骏贤 （网易游戏资深数据库系统工程师 ）

网易游戏对于RPO的要求相对苛刻（数据要求无损）。但更多是以成本最小化为考量实现双活高可用架构。因此目前仅采用同城双副本。

李运华 互联网大厂 资深技术专家

企业是否需要上云取决于成本和技术实力两个主要因素。

  1. 成本考量：
  • 企业规模：一般来说，如果企业的服务器规模在一千台以下，上云通常是成本效益较高的选择。对于规模在一千到五千台之间的企业，上云可能并不一定省成本，而取决于其在云平台上的使用程度。然而，如果服务器规模超过五千台，可能会发现下云（即从云平台迁移到自建环境）会更经济合算，尤其是对于大型企业。这是因为大型企业可能会拥有足够的资源和资金来自建云或自建机房，并且会节省大量成本。
  • 全面成本考量：除了物理服务器成本之外，还需要考虑人员成本、维护成本等方面的费用。这些费用在决定是否上云时也至关重要。
  1. 技术实力：
  • 企业规模与技术实力：大型企业通常拥有更多的人力资源和技术实力，因此更有能力独立管理和运维自己的服务器环境。相比之下，中小型企业可能缺乏专业技能和资源，难以应对复杂的技术挑战，因此更倾向于使用云服务提供商提供的解决方案。
  • 云产品的功能和强大程度：云服务提供商提供了丰富的云产品和服务，包括分布式一致性数据库等高级功能。然而，自行实现这些功能需要大量的时间、资源和技术实力。对于中小型企业而言，使用云平台提供的功能可能更为经济实惠和可行。（ocean base一个几百上千人的团队，从2013年开始，搞了12年）

同城双活和异地多活有哪些方案？

  1. 同城双活方案：

    由于同城机房之间的网络延迟可以做到非常低，通常可以在几毫秒以内，因此同城双核在逻辑上可以看作是一个统一的机房。可以直接按照集群的方式运作，成本和复杂度会低。

  2. 近邻的异地多活：
    这种方案通常是指在相邻的两个城市之间进行异地多活部署。例如，广州与深圳、杭州与上海等相邻城市之间的部署。由于网络延迟相对较低，大约在十毫秒左右，因此可以接受。近邻的异地多活方案通常可以通过分布式一致性算法来实现投票和选举，确保系统的可用性。

  3. 远端的异地多活：
    在距离较远的城市之间进行异地多活部署，如广州与北京之间的部署。网络延迟可能较高（30ms以上），本质上没有办法实现这种集群的运作。

马洪喜（深圳行云创新科技有限公司 CEO）

马老师分享了三个不同企业的案例：

  1. 区域性银行的高可用解决方案：
  • 该银行实施了同城双活的云原生高可用解决方案，这是一个强需求，因为银行业务对高可用性有极高的要求。
  • 他们的方案是基于一个调度器实现的，使得业务在发生故障时可以切换到单机群模式。
  1. 某超大型电器公司的混合云方案：
  • 该公司实施了混合云，将国内业务部署在私有云上，将海外业务部署在AWS上。
  • 这是出于业务需求的考虑，例如海外业务需要在AWS上就近访问。
  1. 某锂电制造企业的工业场景需求：
  • 该企业有着复杂的IT/OT融合场景，需要在制造业中实现微服务和AI的应用。
  • 他们的需求包括在本地数据中心或厂区内的小型数据中心处理数据，而不是将数据从生产线传送回总部或云平台。
  • 制造业趋向于建立一个多级算力体系，包括本地数据中心、云平台和边缘计算，而不仅仅是简单的双活或多活部署。

另外在与公有云对接的过程中，确实会遇到一些挑战和坑：比如公有云平台通常会限制用户在容器服务中运行某些特定类型的应用程序或容器镜像。以及路由设置、网络安全限制等。此外，有些云服务商在网络层面可能会实施一些特殊的技术手段，如MAC地址劫持等，导致一些不必要的麻烦和延迟。

顺炽国 （某制造集团 云平台基础服务负责人 ）

常见的一些互联网应用很多只关注C端的，也就是只需要考虑北线（用户入口）入口流量一个分流跟分发或者流量管控。但是在物联网行业还需要考虑南线（设备入网）的流量管理，这两部分只有配网绑定的阶段需要打通南北两线的数据。

  1. 成本压力：集团的服务器规模正好在一千到五千个主机之间，导致了巨大的成本和运维压力。解决这个问题正在考虑下云。

  2. 业务复杂性：智能家电行业有独特的业务特点，需要同时关注北线（用户入口）和南线（设备入网）的流量管理，确保设备与用户之间的关联和通信畅通。

  3. 多云节点部署：需要根据业务需求，在各个区域部署多云节点，以提供更快的服务响应时间，降低用户体验的糟糕程度。

  4. 单元化思路：采用单元化的思路，尽量减少数据同步带来的问题，通过北线和南线的网关，将业务闭环在单元内，以降低对专线的重度依赖，提高业务稳定性。

张观石（ 泰健科技 CTO）

张老师讲了个故事： 初始阶段，自建CDN成本高，后接入云CDN，但谈判降价困难。后期通过多云CDN架构，平衡质量和成本，使各厂商主动降价争取份额。

他从一个比较新颖的角度谈论了多云架构的优势：根据提供商的服务质量和价格，分配负载份额

另外他谈到了多云架构的优势：

  • 多云并非只为实现多活，而是为了在架构中灵活利用不同云服务的特点和价格优势（使用特定GPU型号的业务只能在相应云上部署，提高架构灵活性）
  • 利用不同云的产品优势，如低价存储，以降低整体成本。

通过多云策略，企业可以增加与云服务商的谈判地位，从而更好地争取资源、降低成本。同时，多云策略也提供了更灵活的资源供给方式，可以根据业务需求在不同云之间调度资源，确保服务的稳定性和容灾能力。

另外由于多云架构的复杂性，监控告警、排障流程等运维问题复杂度增加，需要考虑跨云沟通和统一运维平台的建设。这就引入了另一个问题：如何建立多云融合统一管理（CMDB）

CMDB的核心功能是收集和存储关于云环境中各种资源的详细信息，包括虚拟机、存储、网络设备等。管理员可以实现统一的交互界面，方便地查询、分析和修改资源的配置状态

根据企业对于多云管理的管理要求，可以采用以下几种方式：

  • 十几二十几台服务器，没有必要上CMDB系统，通过管理员登录各云的控制台进行管理

  • 资源管理型：创建虚拟机，配置网络等，基于开源的管理工具（比如rental？）二次开发较为容易，各家云厂商的API接口并不复杂。

  • 应用管理型，属于高级别应用，可以与应用交付系统结合，从应用的视角出发，自动选择合适的云资源来部署和交付应用，基本要采购商业产品。定制化开发。或寻求混合云厂商，有现有的解决方案可选。

–完结–

]]> 今年的中国系统架构师大会（SACC）在我所在的城市广州举办，很荣幸受邀参加。这次能接触到国内最优秀的架构师，学习他们的架构思想和行业经验。对我而言非常有意义。大会分为上下午共4场，我参加了上午的多云多活架构设计专场和下午的AIGC专场。本篇文章就多云多活架构设计专场，我选取几位老师的观点进行分享。（我并不是架构师，只是对架构感兴趣，如有错误，还请指正） [.NET项目实战] Elsa开源工作流组件应用（一）： Elsa工作流简介 https://blog.matoapp.net/posts/6233df02/ 2024-03-15T17:21:00.000Z 2025-09-24T16:30:02.362Z Elsa工作流简介

工作流是什么？

引用维基百科中对工作流的解释：

是对工作流程及其各操作步骤之间业务规则的抽象、概括、描述。工作流建模，即将工作流程中的工作如何前后组织在一起的逻辑和规则在计算机中以恰当的模型进行表示并对其实施计算

Elsa 是一个功能强大的工作流库，支持在任何 .NET 应用程序中执行工作流。Elsa 可以使用C#代码或使用基于Web的可视化设计器生成JSON等方式定义工作流程。

Elsa 可用于多种场景，包括：

  • 长时间运行的工作流程，例如订单履行和产品批准。
  • 运行时间较短的工作流程，例如发送电子邮件和生成 PDF。
  • 计划的工作流，例如发送每日报告。
  • 事件驱动的工作流，例如在用户注册时发送欢迎电子邮件。

Elsa免费且开源，并且有较完善的文档，了解更多请访问官网和官方仓库

工作流的基本概念

要定义一个工作流，需要包含两个最基本的信息：

  1. 对一系列任务的执行过程的描述；
  2. 各任务之间执行关系的描述。

在Elsa中，这些被抽象为：

  1. 活动（Activity）: 执行任务的实体，如：写入文本、发送邮件、执行SQL、执行HTTP请求等；
  2. 工作流（Workflow）：包含多个活动，以及活动之间的执行关系， 如：并行、串行、分支、循环等；

有了活动和工作流，就可以描述一个任务的执行过程了。但为了满足业务的复杂性，Elsa还引入了更多的功能和概念。

上下文系统

活动的本质是执行任务，任务的执行需要数据支持，或返回结果。下游的任务也可能依赖于上游任务的返回结果，如：一个发送执行结果邮件任务，需要知道接收信息和前一个任务的执行结果。上下文系统就是用来支持任务执行过程中的数据传递的。

上下文系统包括：

  • 变量（Variable）；
  • 工作流输入/输出（Input/Output）；
  • 活动输入/输出；
  • 结果（OutCome）。

阻断/恢复功能

一些场景下，任务不会连续执行，需要暂停任务，任务恢复后，需要继续执行。
这些场景包括：

  • 延时触发，或按计时器规则触发的任务；
  • 接收到某个消息才执行的任务。

这些功能在Elsa中使用书签（Bookmark） 和 事件（Event）等类型实现。

设计器（Designer）

硬编码的方式已经无法满足复杂的业务场景，设计器可以将工作流设计为一个图形化的界面，用户可以拖拽活动，连线，设置活动的属性；活动被打包成一个节点（Node），与活动之间的连线表示活动之间的依赖关系。

定义（Definition）与实例化（Instance）

工作流定义描述了一个工作流的结构，比如：名称，变量，包含的活动等，可以理解为一个工作流的模板。

工作流定义在Elsa初始化时会“注册” 到资源池中，每个工作流定义都有一个唯一的ID。

使用设计器生成的工作流，通过序列化成JSON字符串，并持久化到数据库。
使用硬编码创建的工作流，在Elsa初始化时将工作流注册到工作流定义并持久化到数据库。

实例化是根据定义创建一个工作流的实例，工作流实例包含工作流状态（WorkflowState）以及活动实例（ActivityState）。与定义一样，它们通过序列化成JSON字符串，并持久化到数据库。当程序重新启动时，会从数据库中恢复工作流实例。

]]> 工作流定义描述了一个工作流的结构，比如：名称，变量，包含的活动等，可以理解为一个工作流的模板。工作流定义在Elsa初始化时会“注册” 到资源池中，每个工作流定义都有一个唯一的ID。使用设计器生成的工作流，通过序列化成JSON字符串，并持久化到数据库。使用硬编码创建的工作流，在Elsa初始化时将工作流注册到工作流定义并持久化到数据库。实例化是根据定义创建一个工作流的实例，工作流实例包含工作流状态（WorkflowState）以及活动实例（ActivityState）。 开源好用的所见即所得(WYSIWYG)编辑器：Editor.js https://blog.matoapp.net/posts/d2c2fe0c/ 2024-03-11T18:42:00.000Z 2025-09-24T16:30:02.706Z

今天介绍一个开源好用的Web所见即所得(WYSIWYG)编辑器：Editor.js

Editor.js 是一个基于 Web 的所见即所得富文本编辑器，它由CodeX团队开发。源代码托管于Github：https://github.com/codex-team/editor.js

特点

它有两个显著的特点，一个是基于区块（block-styled）的编辑模式，另一个是可以输出干净的数据。

基于区块

基于区块官网是这样解释的：

Editor.js工作区由单独的区块组成：段落、标题、图像、列表、引号等。它们中的每一个都是由 Plugin 提供的独立元素（或更复杂的结构）并由 Editor’s Core 连结。

干净的数据

Editor.js 输出干净的json数据而不是 HTML 标记，虽然对浏览器来说，HTML 是更直观的，但对服务器来说，json更精简更关注内容本身，易于重复使用，存储和传输。

对于控件本身也更易于实现，比如在文本“加粗”和“常规”来回切换，基于json的更改一个属性，总要比基于HTML反复添加和删除标记更简单吧？

界面与交互

在编辑区域，Editor.js提供了区块工具栏(Block Tools)，内联工具栏(Inline Tools)和区块编辑栏(Block Tunes)

他们分别通过 加号 + 按钮，选中区块内容和菜单（六个点和尚按钮）来访问

插件

每个区块都通过插件提供支持，官方提供了常用的插件，当然也可以自己写插件。

官方提供的插件如下图，在sample中，都以cdn方式引入了这些插件，也可以通过npm安装。

标题和文本

序列化后的数据如下图所示，

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "id" : "zcKCF1S7X8",
    "type" : "header",
    "data" : {
        "text" : "Editor.js",
        "level" : 1
    }
},
{
    "id" : "b6ji-DvaKb",
    "type" : "paragraph",
    "data" : {
        "text" : "支持文本，标题，列表，代办，表格，图片，链接，代码片段，引用片段等等"
    }
},

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "id" : "SSBSguGvP7",
    "type" : "list",
    "data" : {
        "style" : "ordered",
        "items" : [
            {
                "content" : "支持普通文本，<i>斜体文本</i>，<b>加粗</b>",
                "items" : []
            },
            {
                "content" : "支持<mark class=\"cdx-marker\">文本高亮</mark>、<a href=\"https://baidu.com\">文本链接</a>、<code class=\"inline-code\">代码片段</code><mark class=\"cdx-marker\"></mark>",
                "items" : []
            }
        ]
    }
},

图片

图片支持Base64编码，和url两种方式上传图片

1
2
3
4
5
6
7
8
9
10
11
{
    "id" : "VYsWoLL7yj",
    "type" : "image",
    "data" : {
        "url" : "data:image/png;base64, ...",
        "caption" : "codex2x.png",
        "withBorder" : false,
        "withBackground" : false,
        "stretched" : false
    }
}

列表

支持有序和无序列表，列表支持嵌套

无序列表：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
            "id" : "i_cVQxn3Tb",
            "type" : "list",
            "data" : {
                "style" : "unordered",
                "items" : [
                    {
                        "content" : " 香蕉",
                        "items" : []
                    },
                    {
                        "content" : " 苹果",
                        "items" : []
                    },
                    {
                        "content" : " 葡萄  ",
                        "items" : []
                    }
                ]
            }
        },

有序列表：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "id" : "nOTdryosj2",
    "type" : "list",
    "data" : {
        "style" : "ordered",
        "items" : [
            {
                "content" : "洗手心",
                "items" : []
            },
            {
                "content" : "搓手背",
                "items" : []
            },
            {
                "content" : "洗指缝",
                "items" : []
            }
        ]
    }
},

嵌套列表：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "id" : "LJjzlmGa-3",
    "type" : "list",
    "data" : {
        "style" : "unordered",
        "items" : [
            {
                "content" : "序章",
                "items" : []
            },
            {
                "content" : "第一章",
                "items" : [
                    {
                        "content" : "第一节",
                        "items" : [
                            {
                                "content" : "a)",
                                "items" : []
                            },
                            {
                                "content" : "b)",
                                "items" : []
                            },
                            {
                                "content" : "c)",
                                "items" : []
                            }
                        ]
                    },
                    {
                        "content" : "第二节",
                        "items" : []
                    }
                ]
            }
        ]
    }
},

Todo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
            "id" : "Hitrs4RqXw",
            "type" : "checklist",
            "data" : {
                "items" : [
                    {
                        "text" : "满意",
                        "checked" : true
                    },
                    {
                        "text" : "一般",
                        "checked" : false
                    },
                    {
                        "text" : "不满意☹️",
                        "checked" : false
                    }
                ]
            }
        },

表格

不代表头：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
    "id" : "xPAQ6AkUiK",
    "type" : "paragraph",
    "data" : {
        "text" : "<b>不带表头</b>"
    }
},
{
    "id" : "_MMoOqlgXs",
    "type" : "table",
    "data" : {
        "withHeadings" : false,
        "content" : [
            [
                "<b>重要紧急</b>",
                "<b>重要不紧急</b>"
            ],
            [
                "吃饭睡觉",
                "订生日蛋糕"
            ],
            [
                "<b>不重要但紧急</b>",
                "<b>不重要不紧急</b>"
            ],
            [
                "上班前定好闹钟",
                "总结这一周的工作"
            ]
        ]
    }
},

带表头：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "id" : "fvfQSljMK8",
    "type" : "table",
    "data" : {
        "withHeadings" : true,
        "content" : [
            [
                "星期一",
                "星期二",
                "星期三",
                "星期四",
                "星期五"
            ],
            [
                "a",
                "b",
                "c",
                "d",
                "e"
            ]
        ]
    }
},

使用

安装

页面中引用Editor.js Core库，可通过npm安装。也可以编译项目，然后引入编译后的js文件。

1
yarn add @editorjs/editorjs

或

1
2
<script src="lib/editorjs/editorjs.umd.js"></script>

创建编辑器实例

在页面创建编辑器

1
2
3
4
5
6
7
8
9
10

import EditorJS from '@editorjs/editorjs';


const editor = new EditorJS({
  /**
   * Id of Element that should contain Editor instance
   */
  holder: 'editorjs'
});

这是一个最小化的示例。你会发现没有那些默认的工具。因此需要在配置中指定工具。

配置工具

可以通过传入配置对象创建编辑器实例。以下是示例

holder指定编辑器的容器元素。

1
2
3
4
5
6
7

window.editor = new window.EditorJS({
    /**
        * Wrapper of Editor
        */
    holder: 'editorjs',

配置工具

配置完成后，区块工具栏将呈现一个较为完整的工具列表。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
    /**
        * Tools list
        */
    tools: {
        paragraph: {
            config: {
                placeholder: "Enter something"
            }
        },

        header: {
            class: Header,
            inlineToolbar: ['link'],
            config: {
                placeholder: 'Header'
            },
            shortcut: 'CMD+SHIFT+H'
        },

        /**
            * Or pass class directly without any configuration
            */
        image: ImageTool,

        list: {
            class: NestedList,
            inlineToolbar: true,
            shortcut: 'CMD+SHIFT+L'
        },

        checklist: {
            class: Checklist,
            inlineToolbar: true,
        },

        quote: {
            class: Quote,
            inlineToolbar: true,
            config: {
                quotePlaceholder: 'Enter a quote',
                captionPlaceholder: 'Quote\'s author',
            },
            shortcut: 'CMD+SHIFT+O'
        },


        marker: {
            class: Marker,
            shortcut: 'CMD+SHIFT+M'
        },

        code: {
            class: CodeTool,
            shortcut: 'CMD+SHIFT+C'
        },

        delimiter: Delimiter,

        inlineCode: {
            class: InlineCode,
            shortcut: 'CMD+SHIFT+C'
        },

        linkTool: LinkTool,

        embed: Embed,

        table: {
            class: Table,
            inlineToolbar: true,
            shortcut: 'CMD+ALT+T'
        },

    },
    

    /**
        * Initial Editor data
        */
    data: obj,
    onReady: function () {
        saveButton.click();
    },
});

本地化

可以通过传入i18n配置对象来设置编辑器的本地化。以下是一个较为完整的中文化示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

i18n: {
    messages: {
        "ui": {
            "blockTunes": {
                "toggler": {
                    "Click to tune": "点击转换",
                    "or drag to move": "拖动调整"
                },
            },
            "inlineToolbar": {
                "converter": {
                    "Convert to": "转换成"
                }
            },
            "toolbar": {
                "toolbox": {
                    "Add": "添加",
                    "Filter": "过滤",
                    "Nothing found": "无内容"
                },
                "popover": {
                    "Filter": "过滤",
                    "Nothing found": "无内容"
                }
            }
        },
        "toolNames": {
            "Text": "段落",
            "Heading": "标题",
            "List": "列表",
            "Warning": "警告",
            "Checklist": "清单",
            "Quote": "引用",
            "Code": "代码",
            "Delimiter": "分割线",
            "Raw HTML": "HTML片段",
            "Table": "表格",
            "Link": "链接",
            "Marker": "突出显示",
            "Bold": "加粗",
            "Italic": "倾斜",
            "InlineCode": "代码片段",
            "Image": "图片"
        },
        "tools": {
            "link": {
                "Add a link": "添加链接"
            },
            "stub": {
                'The block can not be displayed correctly.': '该模块不能放置在这里'
            },
            "image": {
                "Caption": "图片说明",
                "Select an Image": "选择图片",
                "With border": "添加边框",
                "Stretch image": "拉伸图像",
                "With background": "添加背景",
            },
            "code": {
                "Enter a code": "输入代码",
            },
            "linkTool": {
                "Link": "请输入链接地址",
                "Couldn't fetch the link data": "获取链接数据失败",
                "Couldn't get this link data, try the other one": "该链接不能访问，请修改",
                "Wrong response format from the server": "错误响应",
            },
            "header": {
                "Header": "标题",
                "Heading 2": "二级标题",
                "Heading 3": "三级标题",
                "Heading 4": "四级标题",
                "Heading 5": "五级标题",
            },
            "paragraph": {
                "Enter something": "请输入笔记内容",
            },
            "list": {
                "Ordered": "有序列表",
                "Unordered": "无序列表",
            },
            "table": {
                "Heading": "标题",
                "Add column to left": "在左侧插入列",
                "Add column to right": "在右侧插入列",
                "Delete column": "删除列",
                "Add row above": "在上方插入行",
                "Add row below": "在下方插入行",
                "Delete row": "删除行",
                "With headings": "有标题",
                "Without headings": "无标题",
            },
            "quote": {
                "Align Left": "左对齐",
                "Align Center": "居中对齐",
            }
        },
        "blockTunes": {
            "delete": {
                "Delete": "删除",
                'Click to delete': "点击删除"
            },
            "moveUp": {
                "Move up": "向上移"
            },
            "moveDown": {
                "Move down": "向下移"
            },
            "filter": {
                "Filter": "过滤"
            }
        },
    }
}

自定义样式

varaiables.css中包含了大部分的样式变量，更改这些变量可以实现自定义样式。

如通过重写 .root样式选择器可以实现自定义的背景色, 重写.ce-popover 改变弹出框样式等。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
:root {
    --color-bg-main: #F0F0F0;
    --color-border-light: #E8E8EB;
    --color-text-main: #000;
    --selectionColor: #e1f2ff;
}


.ce-popover {
    --border-radius: 6px;
    --width: 200px;
    --max-height: 270px;
    --padding: 6px;
    --offset-from-target: 8px;
    --color-border: #e8e8eb;
    --color-shadow: rgba(13,20,33,0.13);
    --color-background: white;
    --color-text-primary: black;
    --color-text-secondary: #707684;
    --color-border-icon: rgb(201 201 204 / 48%);
    --color-border-icon-disabled: #EFF0F1;
    --color-text-icon-active: #388AE5;
    --color-background-icon-active: rgba(56, 138, 229, 0.1);
    --color-background-item-focus: rgba(34, 186, 255, 0.08);
    --color-shadow-item-focus: rgba(7, 161, 227, 0.08);
    --color-background-item-hover: #eff2f5;
    --color-background-item-confirm: #E24A4A;
    --color-background-item-confirm-hover: #CE4343;
}
.dark-mode {
  --color-border-light: rgba(255, 255, 255,.08);
  --color-bg-main: #1c1e24;
  --color-text-main: #737886;
}


– 完 –

]]> varaiables.css中包含了大部分的样式变量，更改这些变量可以实现自定义样式。如通过重写 .root样式选择器可以实现自定义的背景色, 重写.ce-popover 改变弹出框样式等。:root {– 完 – 在macOS中搭建.NET MAUI开发环境 https://blog.matoapp.net/posts/ddf3f205/ 2023-12-31T00:21:00.000Z 2025-09-24T16:30:02.670Z

准备

  • 一台 macOS Monterey 以上的电脑
  • 安装 XCode13.3 以上
  • 安装 Visual Studio Code

安装扩展

打开Visual Studio Code，按下 Command + Shift + P，输入 install，选择 Extensions: Install Extensions，搜索 MAUI，安装 .NET MAUI 扩展。

安装 .NET

安装 .NET 8 https://dotnet.microsoft.com/zh-cn/download/dotnet

安装工作负载

打开终端，输入以下命令：

1
dotnet workload install maui

安装 Xcode 命令行工具

打开终端，输入以下命令：

1
sudo xcode-select --install

至此，应该可以调试iOS应用了。

调试安卓应用

若要在 Visual Studio Code 中调试 Android 应用，请执行以下操作：

安装 JDK

下载最新版本的 JDK：

https://learn.microsoft.com/zh-cn/java/openjdk/download

安装 JDK：

安装 Android SDK

创建新的 .NET MAUI 项目，在合适的位置打开终端，输入以下命令：

1
dotnet new maui

在项目文件夹中，打开终端，输入以下命令：

1
dotnet build -t:InstallAndroidDependencies -f:net8.0-android -p:AndroidSdkDirectory="<ANDROID SDK DIRECTORY>" -p:AcceptAndroidSDKLicenses=True

在 macOS 上，建议的 Android SDK 目录值为 $HOME/Library/Android/sdk

Android SDK 将自动被创建

安装 Android 模拟器

此时已可以真机调试 Android 应用，如果真机调试不方便，我们需要安装 Android 模拟器。

安装模拟器

前往 Android SDK Manager 所在目录，默认为 $HOME/Library/Android/sdk/cmdline-tools/11.0/bin，打开终端，输入以下命令：

1
./sdkmanager --install emulator

安装镜像

1
./sdkmanager "emulator" "system-images;android-34;google_apis;x86_64"

创建虚拟机

1
./avdmanager create avd -n Pixel5-API34 -k "system-images;android-34;google_apis;x86_64"

另外可以通过切换调试目标中的菜单，查看可用的镜像，选择一个镜像，或创建一个新的镜像。

CMD+SHIFT+P 或 查看->命令面板


选择“创建Android Emulator”

根据提示完成创建

同意许可条款

打开终端，输入以下命令：

1
./sdkmanager --licenses --verbose

按照提示输入 y 同意许可条款。

创建 MAUI 项目

若要创建新的 .NET MAUI 应用，请执行以下操作：

  1. 在资源管理器中，单击“创建 .NET 项目”或按 CMD+SHIFT+P> 选择“.NET: New Project…”。
  2. 选择“.NET MAUI 应用”或“.NET MAUI Blazor 应用”。
  3. 选择空文件夹。 如果文件资源管理器弹出窗口再次打开，则文件夹不为空。
  4. 为项目命名。
  5. 确保项目在解决方案资源管理器中成功加载，然后打开 C# 或 XAML 文件。
  6. 也可以通过单击“文件”>“打开…”在 Visual Studio Code 中打开现有的 .NET MAUI 项目。

调试 MAUI 应用

在 Visual Studio Code 中，按 F5 键或单击“运行”>“启动调试”以调试 .NET MAUI 应用。

调试器选择器将显示可用的调试器。 选择“ .NET MAUI”以启动调试会话。

切换调试目标

在 Visual Studio Code 的资源管理器中，打开项目sln文件，

此时在任务栏出现大括号 {}，点击选择调试目标。

参考资料

扩展主页：
https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui

扩展仓库：
https://github.com/microsoft/vscode-dotnettools

官方文档：
https://learn.microsoft.com/zh-cn/dotnet/maui/get-started/installation?view=net-maui-8.0&tabs=visual-studio-code

]]> 在 Visual Studio Code 中，按 F5 键或单击“运行”>“启动调试”以调试 .NET MAUI 应用。在 macOS 上，建议的 Android SDK 目录值为 $HOME/Library/Android/sdk。此时已可以真机调试 Android 应用，如果真机调试不方便，我们需要安装 Android 模拟器。另外可以通过切换调试目标中的菜单，查看可用的镜像，选择一个镜像，或创建一个新的镜像。在 Visual Studio Code 的资源管理器中，打开项目sln文件，