shumengya/cwd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加评论组件多语言配置相关文档

Browse Source 
- 在前端配置指南中增加 `lang` 配置项说明及多语言优先级规则
- 在公开配置接口文档中添加 `adminLanguage` 和 `widgetLanguage` 字段
- 更新管理后台功能设置接口文档，包含语言配置字段及详细说明
This commit is contained in:
anghunk
2026-02-10 14:48:56 +08:00
parent ccd558090c
commit 231571091c
3 changed files with 81 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/api/admin/feature-settings.md
View File

@@ -1,17 +1,17 @@
# 功能设置相关
管理各项功能开关的接口，包括点赞功能、图片灯箱预览、评论占位符、域名可见性等。
管理各项功能开关的接口，包括点赞功能、图片灯箱预览、评论占位符、域名可见性、多语言等。
## 获取功能设置
```
GET /admin/settings/feature
GET /admin/settings/features
```
获取当前的功能开关配置。
- 方法：`GET`
- 路径：`/admin/settings/feature`
- 路径：`/admin/settings/features`
- 鉴权：需要 Bearer Token
**成功响应**
@@ -24,38 +24,49 @@ GET /admin/settings/feature
"enableArticleLike": true,
"enableImageLightbox": true,
"commentPlaceholder": "发表你的看法...",
"visibleDomains": ["example.com", "blog.example.com"]
"visibleDomains": ["example.com", "blog.example.com"],
"adminLanguage": "zh-CN",
"widgetLanguage": "auto"
}
```
字段说明：
| 字段名 | 类型 | 说明 |
| -------------------- | ------ | ---------------------- |
| `enableCommentLike` | boolean | 是否启用评论点赞功能 |
| `enableArticleLike` | boolean | 是否启用文章点赞功能 |
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能 |
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本 |
| `visibleDomains` | string[] | 允许显示评论组件的域名列表 |
| 字段名 | 类型 | 说明 |
| -------------------- | -------- | -------------------------------------------------------------------- |
| `enableCommentLike` | boolean | 是否启用评论点赞功能 |
| `enableArticleLike` | boolean | 是否启用文章点赞功能 |
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能 |
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认文案 |
| `visibleDomains` | string[] | 允许显示评论组件的域名列表 |
| `adminLanguage` | string \| null | 管理后台界面语言代码，如 `zh-CN`、`en-US`，为空则使用默认语言 |
| `widgetLanguage` | string \| null | 评论组件默认语言代码，支持 `auto` 自动根据浏览器语言选择 |
语言相关字段说明：
- 当配置了 `adminLanguage` 时，管理后台会优先使用该语言渲染界面
- 当配置了 `widgetLanguage` 时，评论前端组件会以此作为默认语言；
- 如果前端实例化时显式传入 `lang` 配置项，则以前端为最高优先级
- 当前端未传入 `lang` 时，顺序为：后端 `widgetLanguage` → 自动检测浏览器语言（如 `zh-CN`/`en-US`）
## 更新功能设置
```
PUT /admin/settings/feature
PUT /admin/settings/features
```
更新功能开关配置。
- 方法：`PUT`
- 路径：`/admin/settings/feature`
- 路径：`/admin/settings/features`
- 鉴权：需要 Bearer Token
**请求头**
| 名称 | 必填 | 示例 |
| -------------- | ---- | ------------------ |
| `Content-Type` | 是 | `application/json` |
| `Authorization` | 是 | `Bearer <token>` |
| 名称 | 必填 | 示例 |
| --------------- | ---- | -------------------- |
| `Content-Type` | 是 | `application/json` |
| `Authorization` | 是 | `Bearer <token>` |
**请求体**
@@ -65,25 +76,31 @@ PUT /admin/settings/feature
"enableArticleLike": true,
"enableImageLightbox": true,
"commentPlaceholder": "发表你的看法...",
"visibleDomains": ["example.com", "blog.example.com"]
"visibleDomains": ["example.com", "blog.example.com"],
"adminLanguage": "zh-CN",
"widgetLanguage": "auto"
}
```
字段说明：
| 字段名 | 类型 | 必填 | 说明 |
| -------------------- | ------- | ---- | ---------------------- |
| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 |
| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 |
| `enableImageLightbox` | boolean | 否 | 是否启用评论图片灯箱预览功能 |
| `commentPlaceholder` | string | 否 | 评论输入框的占位符文本 |
| `visibleDomains` | string[] | 否 | 允许显示评论组件的域名列表 |
| 字段名 | 类型 | 必填 | 说明 |
| -------------------- | -------- | ---- | -------------------------------------------------------------------- |
| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 |
| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 |
| `enableImageLightbox` | boolean | 否 | 是否启用评论图片灯箱预览功能 |
| `commentPlaceholder` | string | 否 | 评论输入框的占位符文本 |
| `visibleDomains` | string[] | 否 | 允许显示评论组件的域名列表 |
| `adminLanguage` | string | 否 | 管理后台界面语言代码，留空则不修改当前配置 |
| `widgetLanguage` | string | 否 | 评论组件默认语言代码，支持 `auto` 表示自动根据浏览器语言选择 |
**说明**：
- `enableImageLightbox`：启用后，评论内容中的图片可以点击放大预览
- `commentPlaceholder`：自定义评论输入框的占位符文本，留空则使用默认文本
- `visibleDomains`：设置后，只有在此列表中的域名可以正常显示评论组件，其他域名将被隐藏。留空或为 `null` 表示不限制域名。
- `visibleDomains`：设置后，只有在此列表中的域名可以正常显示评论组件，其他域名将被隐藏。留空或为 `null` 表示不限制域名
- `adminLanguage`：仅影响管理后台界面，不影响评论组件语言
- `widgetLanguage`：作为评论组件默认语言，当前端未主动传入 `lang` 时才生效
**成功响应**

30
docs/api/public/config.md
View File

@@ -35,24 +35,28 @@ GET /api/config/comments
"enableCommentLike": true,
"enableArticleLike": true,
"enableImageLightbox": true,
"commentPlaceholder": "发表你的看法..."
"commentPlaceholder": "发表你的看法...",
"adminLanguage": "zh-CN",
"widgetLanguage": "auto"
}
```
字段说明：
| 字段名 | 类型 | 说明 |
| -------------------- | ------ | -------------------------------------------------------------------- |
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 |
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制 |
| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） |
| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） |
| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） |
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） |
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 |
| 字段名 | 类型 | 说明 |
| -------------------- | ----------------- | -------------------------------------------------------------------- |
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 |
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制 |
| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） |
| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） |
| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） |
| `enableImageLightbox`| boolean | 是否启用评论图片灯箱预览功能（默认 false） |
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 |
| `adminLanguage` | string \| null | 管理后台界面语言代码，如 `zh-CN`、`en-US`，仅供后台使用 |
| `widgetLanguage` | string \| null | 评论前端组件默认语言代码，支持 `auto` 自动根据浏览器语言选择 |
**错误响应**

23
docs/guide/frontend-config.md
View File

@@ -29,8 +29,8 @@ CWD 评论组件采用 **Shadow DOM** 技术构建，基于独立根节点渲染
el: '#comments', // 必填
apiBaseUrl: 'https://your-api.example.com', // 必填，换成你的 API 地址
postSlug: 'post-unique-id-001', // 选填，自定义评论标识符，用于跨路径/多语言聚合
siteId: 'blog', // 选填，推荐配置，用于多站点数据隔离。
siteId: 'blog', // 选填，推荐配置，用于多站点数据隔离
lang: 'auto', // 选填，评论组件语言，详见下方说明
});
comments.mount();
</script>
@@ -60,10 +60,29 @@ https://cwd.js.org/cwd.js
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
| `siteId` | `string` | 否 | `''` | 站点 ID，用于多站点数据隔离，推荐配置 |
| `postSlug` | `string` | 否 | `window.location.pathname` | 自定义评论标识符，用于跨路径/多语言聚合 |
| `lang` | `string` | 否 | `auto` | 评论组件语言代码，支持 `zh-CN`、`en-US`、`fr` 等，`auto` 表示自动根据浏览器语言选择 |
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
| `customCssUrl` | `string` | 否 | - | 自定义样式表 URL，追加到 Shadow DOM 底部 |
### 多语言配置说明
评论组件语言的优先级如下：
1. 前端实例化时传入的 `lang` 参数（最高优先级）
2. 后端在「功能设置」中配置的 `widgetLanguage`（通过 `/admin/settings/features` 接口下发）
3. 浏览器语言自动检测（当以上两项都为空或为 `auto` 时生效）
推荐做法：
- 后端在管理后台中设置一个全局默认语言（`widgetLanguage`），例如 `zh-CN`
- 不同语言站点如有特殊需求，再在前端实例化时通过 `lang` 明确指定
> [!note] 目前支持的语言有：
> `zh-CN` `en-US` `zh-TW` `es` `pt` `fr` `de` `ja` `ko` `ru` `it` `nl` `ar` `hi` `id`
如需适配其他语言，请联系我们，我们会在后续版本中添加对其他语言的支持，或者提交 pr。
头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。
当 `/admin/settings/comments` 中配置了“评论博主邮箱”（`adminEmail`）时：