feat(ui/conf): add preferRemoteConf option (#1000) (#1011)

Add `preferRemoteConf` option (disabled by default). Local config now takes priority, addressing the issue where remote config previously overrode local settings. (Closes #1000) Updated config merging logic in `mount.ts`. Deprecated `useBackendConf` in favor of `preferRemoteConf`. (The prerequisite PR is #1007) BREAKING CHANGE: UI client now prioritizes local config in the latest version, whereas previously, the remote config would override it. (See #1011)
ArtalkJS · Oct 18, 2024 · bd81b7c · bd81b7c
1 parent f6c99e9
commit bd81b7c
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 17 deletions.
diff --git a/docs/docs/en/guide/frontend/config.md b/docs/docs/en/guide/frontend/config.md
@@ -1,18 +1,20 @@
 # UI Configuration
 
-UI configuration also known as Client (Front-end) configuration, is the configuration of the Artalk interface.
+UI configuration also known as Client (Frontend) configuration, is the configuration of the Artalk interface.
 
-You can modify the UI configuration in the "[Dashboard](./sidebar.md#dashboard)" without changing the front-end code. Additionally, [Configuration files](../backend/config.md#frontend-configuration-frontend) and [Environment variables](../env.md#ui-settings) are also supported.
+You can modify the UI configuration in the "[Dashboard](./sidebar.md#dashboard)" without changing the frontend code. Additionally, [Configuration files](../backend/config.md#frontend-configuration-frontend) and [Environment variables](../env.md#ui-settings) are also supported.
 
 The priority of UI configuration is as follows:
 
 ```
-Environment Variables > Configuration File = Dashboard > Front-end Code
+Frontend Code > Environment Variables > Dashboard = Configuration File
 ```
 
+If you have modified the UI configuration through environment variables, configuration files, or the Dashboard, but the changes are not taking effect, please consider the issue of UI configuration priority.
+
 ## Configuring the Interface via `Artalk.init`
 
-When initializing with `Artalk.init` on the front-end page, pass parameters to configure the interface. Below are all the available configuration options.
+When initializing with `Artalk.init` on the frontend page, pass parameters to configure the interface. Below are all the available configuration options.
 
 ```js
 const artalk = Artalk.init({
@@ -83,14 +85,20 @@ Deploy the backend and ensure that the backend address is accessible from the fr
 
 Artalk supports unified management of multiple sites, this item is used for site isolation.
 
-### useBackendConf
+### preferRemoteConf
 
-**Refer to Backend Configuration**
+**Prefer Remote Configuration**
 
 - Type: `Boolean`
-- Default: `true` (enabled by default)
+- Default: `false` (disabled by default)
+
+This config option is disabled by default, meaning Artalk will prioritize using local config. Local config refers to the settings passed through `Artalk.init` in the frontend code.
+
+When enabled, Artalk will prioritize using remote config. If the remote config does not exist, it will resort to using the local config. Remote config refers to the settings returned by the backend server program, allowing for dynamic config of the Artalk client. You can modify the user interface config in the "[Dashboard](./sidebar.md#dashboard)".
 
-You can define the front-end configuration in the backend configuration file, so that the front-end configuration always refers to the backend.
+::: warning Update Notice
+As of version v2.10.0, the `useBackendConf` configuration option has been deprecated and is always `true`. Please use `preferRemoteConf` instead.
+:::
 
 ## Internationalization (i18n)
 
@@ -530,4 +538,4 @@ Allow height limit area to scroll.
 - Type: `Boolean`
 - Default: `true`
 
-Display a warning prompt when the front-end and back-end versions are incompatible.
+Display a warning prompt when the frontend and backend versions are incompatible.
diff --git a/docs/docs/zh/guide/frontend/config.md b/docs/docs/zh/guide/frontend/config.md
@@ -5,9 +5,11 @@
 界面配置的优先级如下：
 
 ```
-环境变量 > 配置文件 = 控制中心 > 前端代码
+前端代码 > 环境变量 > 控制中心 = 配置文件
 ```
 
+如果你通过环境变量、配置文件或是在控制中心修改了界面配置，遇到了配置未生效的情况，请考虑配置优先级的问题。
+
 ## 通过 `Artalk.init` 配置界面
 
 在前端页面调用 `Artalk.init` 初始化时传入参数来配置界面，本文列出了所有可用的配置项。
@@ -81,14 +83,20 @@ artalk.update({ ... })
 
 Artalk 支持多站点统一管理，此项用于站点隔离。
 
-### useBackendConf
+### preferRemoteConf
 
-**引用后端的配置**
+**优先使用远程配置**
 
 - 类型：`Boolean`
-- 默认值：`true`（默认启用）
+- 默认值：`false`（默认关闭）
+
+默认情况下，该配置项为关闭状态，Artalk 界面配置优先级为：优先使用本地的配置。本地配置是指在前端代码中通过 `Artalk.init` 传入的配置。
+
+开启后，Artalk 会优先使用远程配置，如果远程配置不存在则使用本地配置。远程配置是指后端服务器程序返回的配置，用于动态配置 Artalk 客户端。你可以在「[控制中心](./sidebar.md#控制中心)」中修改用户界面的配置。
 
-可以在后端的配置文件中定义前端的配置，让前端配置始终引用后端。
+::: warning 更新注意
+从 v2.10.0 开始，`useBackendConf` 配置项已废弃并始终为 `true`，请使用 `preferRemoteConf` 替代。
+:::
 
 ## 国际化 (i18n)
 

diff --git a/ui/artalk/index.html b/ui/artalk/index.html
@@ -200,7 +200,6 @@
         pageTitle: 'Artalk Home',
         server: 'http://localhost:23366',
         site: 'ArtalkDocs',
-        //useBackendConf: true,
       })
 
       window.artalk = artalk

diff --git a/ui/artalk/src/defaults.ts b/ui/artalk/src/defaults.ts
@@ -54,6 +54,7 @@ export const Defaults: Readonly<RequiredExcept<Config, ExcludedKeys>> = {
   reqTimeout: 15000,
   versionCheck: true,
   useBackendConf: true,
+  preferRemoteConf: false,
   listUnreadHighlight: false,
   pvAdd: true,
   fetchCommentsOnInit: true,

diff --git a/ui/artalk/src/mount.ts b/ui/artalk/src/mount.ts
@@ -44,7 +44,7 @@ export async function mount(localConf: ConfigPartial, ctx: Context) {
   }
 
   const remoteConf = handleConfFormServer(data.frontend_conf || {})
-  conf = mergeDeep(conf, remoteConf)
+  conf = conf.preferRemoteConf ? mergeDeep(conf, remoteConf) : mergeDeep(remoteConf, conf)
 
   // Apply local + remote conf
   ctx.updateConf(conf)

diff --git a/ui/artalk/src/types/config.ts b/ui/artalk/src/types/config.ts
@@ -139,9 +139,30 @@ export interface Config {
   /** Enable version check */
   versionCheck: boolean
 
-  /** Use backend configuration */
+  /**
+   * Use remote configuration (from the backend server)
+   *
+   * @deprecated
+   * The `useBackendConf` is always `true` and planned to be removed in the future.
+   *
+   * Please use `preferRemoteConf` to control the priority of the remote and local configuration.
+   *
+   * @default true
+   */
   useBackendConf: boolean
 
+  /**
+   * Prefer to use the local configuration if available
+   *
+   * @note
+   * If `true`, the local config will be used as a fallback (remote config first).
+   *
+   * If `false`, the local config will override the remote config (local config first).
+   *
+   * @default false
+   */
+  preferRemoteConf: boolean
+
   /** Localization settings */
   locale: I18n | string