From 2b20dc7eef9ea2580da77503c745447cbf5113e1 Mon Sep 17 00:00:00 2001 From: alexma233 Date: Tue, 16 Dec 2025 16:35:41 +0800 Subject: [PATCH] refactor(analytics): extract umami as provider and document provider config --- README.md | 11 +- README.zh-Hans.md | 11 +- assets/js/analytics.js | 8 ++ assets/js/main.js | 4 +- layouts/partials/analytics-block-notice.html | 125 +++++------------- layouts/partials/analytics.html | 50 ++++--- .../providers/umami-block-notice.html | 100 ++++++++++++++ .../partials/analytics/providers/umami.html | 24 ++++ layouts/partials/body.html | 2 +- 9 files changed, 211 insertions(+), 124 deletions(-) create mode 100644 assets/js/analytics.js create mode 100644 layouts/partials/analytics/providers/umami-block-notice.html create mode 100644 layouts/partials/analytics/providers/umami.html diff --git a/README.md b/README.md index 4357fa0..9090136 100644 --- a/README.md +++ b/README.md @@ -114,8 +114,10 @@ defaultContentLanguageInSubdir = true # Note: Max latest posts shown on the homepage; shows “View more posts” when exceeded. recentPostsLimit = 4 [params.analytics] - # Note: Umami analytics; replace with your own script URL and site ID. Leave empty to skip loading. - [params.analytics.umami] + # Note: Analytics provider name (required unless only one provider exists under `providers`). + provider = 'umami' + # Note: Umami analytics provider config; replace with your own script URL and site ID. Leave empty to skip loading. + [params.analytics.providers.umami] scriptUrl = 'https://umami.example.com/script.js' websiteId = '5b14b1a3-b5c6-4961-b1a8-32c1819069f8' # dataHost = 'https://umami.example.com' # Optional: override data-host. @@ -207,5 +209,6 @@ hugo --minify - `params.theme.defaultMode`: `auto` / `light` / `dark`. - `params.theme.defaultGlassStrength`: `soft` / `balanced` / `bold`. - `params.theme.defaultReaderWidth` or `params.theme.defaultReaderWidthValue`: Width preset or custom rem value (custom overrides preset). -- `params.analytics.umami.scriptUrl` / `params.analytics.umami.websiteId`: Enable Umami tracking; optional `dataHost`/`dataDomains` to control reporting hosts/domains. -- `params.analytics.umami.blockNotice`: Detect blocked Umami requests and surface a dismissible edge banner. +- `params.analytics.provider`: Analytics provider name (e.g. `umami`). +- `params.analytics.providers.umami.scriptUrl` / `params.analytics.providers.umami.websiteId`: Enable Umami tracking; optional `dataHost`/`dataDomains` to control reporting hosts/domains. +- `params.analytics.providers.umami.blockNotice`: Detect blocked Umami requests and surface a dismissible edge banner. diff --git a/README.zh-Hans.md b/README.zh-Hans.md index 7da206b..b5e276d 100644 --- a/README.zh-Hans.md +++ b/README.zh-Hans.md @@ -106,8 +106,10 @@ defaultContentLanguageInSubdir = true [params.home] recentPostsLimit = 4 # 说明：主页展示的最新文章数量上限，超出时显示“查看更多文章”按钮。 [params.analytics] - # 说明：Umami 统计脚本配置，替换为自己的部署地址与 site id；留空则不输出脚本。 - [params.analytics.umami] + # 说明：统计 provider 名称（建议显式填写；若 providers 下仅配置 1 个 provider，可省略）。 + provider = 'umami' + # 说明：Umami 统计 provider 配置，替换为自己的部署地址与 site id；留空则不输出脚本。 + [params.analytics.providers.umami] scriptUrl = 'https://umami.example.com/script.js' websiteId = '5b14b1a3-b5c6-4961-b1a8-32c1819069f8' # dataHost = 'https://umami.example.com' # 可选：自定义 data-host。 @@ -197,5 +199,6 @@ hugo --minify - `params.theme.defaultMode`：`auto` / `light` / `dark`。 - `params.theme.defaultGlassStrength`：`soft` / `balanced` / `bold`。 - `params.theme.defaultReaderWidth` 或 `params.theme.defaultReaderWidthValue`：阅读区宽度预设或自定义 rem 值（自定义优先）。 -- `params.analytics.umami.scriptUrl` / `params.analytics.umami.websiteId`：Umami 统计脚本的地址与站点 ID，可选 `dataHost` / `dataDomains` 控制上报域名。 -- `params.analytics.umami.blockNotice`：检测统计脚本被拦截时显示贴边提示，可永久忽略。 +- `params.analytics.provider`：统计 provider 名称（例如 `umami`）。 +- `params.analytics.providers.umami.scriptUrl` / `params.analytics.providers.umami.websiteId`：Umami 统计脚本的地址与站点 ID，可选 `dataHost` / `dataDomains` 控制上报域名。 +- `params.analytics.providers.umami.blockNotice`：检测统计脚本被拦截时显示贴边提示，可永久忽略。 diff --git a/assets/js/analytics.js b/assets/js/analytics.js new file mode 100644 index 0000000..1795bc3 --- /dev/null +++ b/assets/js/analytics.js @@ -0,0 +1,8 @@ +import { setupUmamiBlockNotice } from './umami-block-notice.js'; + +// 说明：Analytics provider 初始化入口。 +// 用途：集中挂载各 provider 的前端增强逻辑；未启用的 provider 会在内部自行 no-op。 +export const setupAnalytics = () => { + setupUmamiBlockNotice(); +}; + diff --git a/assets/js/main.js b/assets/js/main.js index 764f067..6d386b8 100644 --- a/assets/js/main.js +++ b/assets/js/main.js @@ -2,7 +2,7 @@ import { setupAppNavigation } from './app-navigation.js'; import { setupSettingsPanel } from './settings-panel.js'; import { setupCodeBlocks } from './code-blocks.js'; import { setupArticleOutline } from './article-outline.js'; -import { setupUmamiBlockNotice } from './umami-block-notice.js'; +import { setupAnalytics } from './analytics.js'; import { setupPagesMenu } from './pages-menu.js'; // 说明：集中触发初始化逻辑，确保各个组件在 DOM 就绪后挂载事件。 @@ -12,7 +12,7 @@ const bootstrap = () => { setupSettingsPanel(); setupCodeBlocks(); setupArticleOutline(); - setupUmamiBlockNotice(); + setupAnalytics(); }; if (document.readyState === 'loading') { diff --git a/layouts/partials/analytics-block-notice.html b/layouts/partials/analytics-block-notice.html index 61d65b1..a43d4c9 100644 --- a/layouts/partials/analytics-block-notice.html +++ b/layouts/partials/analytics-block-notice.html @@ -1,95 +1,30 @@ -{{- with site.Params.analytics }} - {{- with .umami }} - {{- $src := or .scriptURL .scriptUrl -}} - {{- $websiteId := .websiteId -}} - {{- $blockNotice := default false .blockNotice -}} - {{- if and $src $websiteId $blockNotice }} - {{/* 说明：Umami 拦截检测提示条，占位元素默认隐藏，待 JS 判定后再显式展示。 */}} - - - {{- end }} - {{- end }} -{{- end }} +{{- /* + 说明：Analytics provider 分发入口（拦截检测提示）。 + 用途：根据 `params.analytics.provider` 渲染对应 provider 的占位提示 UI。 + 约定：同 `partials/analytics.html` 的 provider 推断与配置读取策略。 +*/ -}} +{{- with site.Params.analytics -}} + {{- $analytics := . -}} + {{- $provider := "" -}} + {{- with $analytics.provider -}} + {{- $provider = lower . -}} + {{- end -}} + + {{- $providers := $analytics.providers | default dict -}} + + {{- if and (not $provider) (eq (len $providers) 1) -}} + {{- range $name, $_ := $providers -}} + {{- if not $provider -}} + {{- $provider = lower $name -}} + {{- end -}} + {{- end -}} + {{- end -}} + + {{- if $provider -}} + {{- $partial := printf "analytics/providers/%s-block-notice.html" $provider -}} + {{- $config := index $providers $provider -}} + {{- if templates.Exists (printf "partials/%s" $partial) -}} + {{- partial $partial (dict "Config" $config "Context" $) -}} + {{- end -}} + {{- end -}} +{{- end -}} diff --git a/layouts/partials/analytics.html b/layouts/partials/analytics.html index 913bdc5..e93e4c3 100644 --- a/layouts/partials/analytics.html +++ b/layouts/partials/analytics.html @@ -1,18 +1,32 @@ -{{- with site.Params.analytics }} - {{- with .umami }} - {{- $src := or .scriptURL .scriptUrl -}} - {{- $websiteId := .websiteId -}} - {{- $blockNotice := default false .blockNotice -}} - {{- if and $src $websiteId }} - {{/* 说明：按 params.analytics.umami 配置注入 Umami 统计脚本，defer 避免阻塞渲染。 */}} - - {{- end }} - {{- end }} -{{- end }} +{{- /* + 说明：Analytics provider 分发入口。 + 用途：根据 `params.analytics.provider` 渲染对应 provider 的脚本注入。 + 约定： + - 推荐：显式设置 `params.analytics.provider` + `params.analytics.providers.`。 + - 若未设置 `provider` 且仅配置了 1 个 `providers`，会自动选用该 provider。 +*/ -}} +{{- with site.Params.analytics -}} + {{- $analytics := . -}} + {{- $provider := "" -}} + {{- with $analytics.provider -}} + {{- $provider = lower . -}} + {{- end -}} + + {{- $providers := $analytics.providers | default dict -}} + + {{- if and (not $provider) (eq (len $providers) 1) -}} + {{- range $name, $_ := $providers -}} + {{- if not $provider -}} + {{- $provider = lower $name -}} + {{- end -}} + {{- end -}} + {{- end -}} + + {{- if $provider -}} + {{- $partial := printf "analytics/providers/%s.html" $provider -}} + {{- $config := index $providers $provider -}} + {{- if templates.Exists (printf "partials/%s" $partial) -}} + {{- partial $partial (dict "Config" $config "Context" $) -}} + {{- end -}} + {{- end -}} +{{- end -}} diff --git a/layouts/partials/analytics/providers/umami-block-notice.html b/layouts/partials/analytics/providers/umami-block-notice.html new file mode 100644 index 0000000..c2b989a --- /dev/null +++ b/layouts/partials/analytics/providers/umami-block-notice.html @@ -0,0 +1,100 @@ +{{- /* + 说明：Umami analytics provider（拦截检测提示）。 + 用途：当开启 `blockNotice` 时输出占位 DOM，供前端脚本在检测失败后展示提示。 + 注意：需要同时满足 `scriptUrl` + `websiteId` + `blockNotice=true` 才输出，避免无意义渲染。 +*/ -}} +{{- $config := .Config -}} +{{- with $config }} + {{- $src := or .scriptURL .scriptUrl -}} + {{- $websiteId := or .websiteId .websiteID -}} + {{- $blockNotice := default false .blockNotice -}} + {{- if and $src $websiteId $blockNotice }} + {{/* 说明：Umami 拦截检测提示条，占位元素默认隐藏，待 JS 判定后再显式展示。 */}} + + + {{- end }} +{{- end }} + diff --git a/layouts/partials/analytics/providers/umami.html b/layouts/partials/analytics/providers/umami.html new file mode 100644 index 0000000..0a7e572 --- /dev/null +++ b/layouts/partials/analytics/providers/umami.html @@ -0,0 +1,24 @@ +{{- /* + 说明：Umami analytics provider。 + 用途：根据 provider 配置注入 Umami 跟踪脚本。 + 注意： + - 仅支持 `params.analytics.providers.umami`（不兼容旧版 `params.analytics.umami`）。 + - 仅当 `scriptUrl`(或 `scriptURL`) 与 `websiteId` 同时存在时才会输出脚本。 +*/ -}} +{{- $config := .Config -}} +{{- with $config }} + {{- $src := or .scriptURL .scriptUrl -}} + {{- $websiteId := or .websiteId .websiteID -}} + {{- $blockNotice := default false .blockNotice -}} + {{- if and $src $websiteId }} + {{/* 说明：defer 避免阻塞渲染；data-* 交由 Umami 脚本读取。 */}} + + {{- end }} +{{- end }} diff --git a/layouts/partials/body.html b/layouts/partials/body.html index 59b4721..5ba840a 100644 --- a/layouts/partials/body.html +++ b/layouts/partials/body.html @@ -91,5 +91,5 @@ {{ end }} {{/* 说明：右下角设置按钮及卡片交互入口。 */}} {{ partial "settings-panel.html" . }} -{{/* 说明：若 Umami 被拦截，则在页面边缘提示用户相关功能不可用。 */}} +{{/* 说明：若统计脚本被拦截，则在页面边缘提示用户相关功能不可用（具体由 provider 决定）。 */}} {{ partial "analytics-block-notice.html" . }} -- 2.51.2