Skip to content

Commit a25d7e7

Browse files
byodianbyodian
committed
docs: how to customize the template and theme
1 parent 842b48c commit a25d7e7

File tree

2 files changed

+303
-0
lines changed

2 files changed

+303
-0
lines changed

‎README.md

+2
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818

1919
https://github.com/user-attachments/assets/d12a1009-a27a-4dae-a2e5-727f3b982e3b
2020

21+
[如何自定义自己的模版和主题](./docs/how-to-custom-template.md)
22+
2123
## 特性
2224
- 快速文字转图片，大幅提高内容创作效率
2325
- 内置多种模版和主题色，**更多模版还在开发中**

‎docs/how-to-custom-template.md

+301
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
## 如何自定义模版主题
2+
3+
本指南分为两个部分：模版结构介绍和如何自定义模版样式。
4+
5+
## 模版结构介绍
6+
模版结构分为以下三个部分。其中，二级内容(sub-container) 位于一级标题的正文 (main-content) 中。
7+
8+
1. 大标题和描述 (hero)
9+
2. 一级标题和正文 (main)
10+
3. 二级标题和正文 (sub)
11+
12+
### 模版HTML结构
13+
14+
```html
15+
<div class="one-container">
16+
<div class="one-list">
17+
<!-- 大标题区域 hero-container -->
18+
<div class="hero-container">
19+
20+
<!-- 大标题 hero-title -->
21+
<div class="hero-title">
22+
<p>...</p>
23+
</div>
24+
25+
<!-- 大标题描述 hero-content -->
26+
<div class="hero-content">
27+
28+
<!-- 富文本编辑器生成的内容 -->
29+
<p>...</p>
30+
<blockquote>
31+
<p>good morning</p>
32+
</blockquote>
33+
34+
<!-- 图片区域，位于描述内容的底部 -->
35+
<div data-class="oneimg-images">
36+
<img alt="chat_id.png" class="object-cover w-full"
37+
src="blob:https://oneimgai.com/ce65176f-87c2-468b-8315-9b72a980b952">
38+
</div>
39+
</div>
40+
</div>
41+
42+
<!-- 一级标题区域 main-container -->
43+
<div class="main-container">
44+
<!-- 一级标题 main-title -->
45+
<div class="main-title">
46+
<!-- 富文本编辑器生成的内容 -->
47+
<p>...</p>
48+
</div>
49+
50+
<!-- 一级标题正文（含二级标题和正文）main-content -->
51+
<div class="main-content">
52+
<!-- 富文本编辑器生成的内容 -->
53+
<p>...</p>
54+
<blockquote>
55+
<p>good morning</p>
56+
</blockquote>
57+
58+
<!-- 一级标题正文图片区域，位于正文的底部 -->
59+
<div data-class="oneimg-images">
60+
<img alt="chat_id.png" class="object-cover w-full"
61+
src="blob:https://oneimgai.com/ce65176f-87c2-468b-8315-9b72a980b952">
62+
</div>
63+
64+
<!-- 二级标题区域 sub-container -->
65+
<div class="sub-container">
66+
<!-- 二级标题 sub-title -->
67+
<div class="sub-title">
68+
<!-- 富文本编辑器生成的内容 -->
69+
<p>...</p>
70+
</div>
71+
72+
<!-- 二级标题的正文 sub-content -->
73+
<div class="sub-content">
74+
<!-- 富文本编辑器生成的内容 -->
75+
<p>...</p>
76+
77+
<!-- 二级标题正文图片区域，位于正文的底部 -->
78+
<div data-class="oneimg-images">
79+
<img alt="chat_id.png" class="object-cover w-full"
80+
src="blob:https://oneimgai.com/ce65176f-87c2-468b-8315-9b72a980b952">
81+
</div>
82+
</div>
83+
</div>
84+
<div class="sub-container">...</div>
85+
<!-- ...更多二级标题和正文 -->
86+
</div>
87+
</div>
88+
89+
<div class="main-container">...</div>
90+
<!-- ...更多一级标题和正文 -->
91+
</div>
92+
</div>
93+
```
94+
95+
### 模版CSS样式
96+
97+
使用 CSS-in-JS 动态生成的 CSS 样式，CSS 类名做了简化处理。
98+
99+
```css
100+
.hero-container {}
101+
.hero-title {}
102+
.hero-content {}
103+
.main-container {}
104+
.main-title {}
105+
.main-content {}
106+
.sub-container {}
107+
.sub-title {}
108+
.sub-content {}
109+
```
110+
111+
## 如何自定义模版样式和颜色主题
112+
113+
自定义模版和主题分为三个步骤：
114+
115+
1. 编写模版样式
116+
2. 编写颜色主题
117+
3. 配置模版变量
118+
119+
由于本项目使用 CSS-in-JS 方案 [tss-react](https://www.tss-react.dev) 在运行时动态生成样式主题，你需要在 typescript 文件中编写模版的 CSS 样式。
120+
121+
在项目模版 [src/theme/templates](https://github.com/byodian/oneimg/tree/main/src/theme/templates) 文件夹中创建一个模版文件夹，比如 demo-template
122+
123+
在 demo-template 模版文件夹中分别创建三个文件：
124+
1. `demo-template.ts` - 模版的 CSS-in-JS 样式
125+
2. `demo-color-variables.ts` - 模版主题颜色的 CSS 自定义变量
126+
3. `index.ts` - 入口文件
127+
128+
129+
`index.ts` 文件内容
130+
131+
```ts
132+
export * from './demo-template'
133+
export * from './demo-color-variables'
134+
```
135+
136+
### 编写模版样式
137+
138+
`demo-template.ts` 中的 CSS-in-JS 会使用 tss-react 动态生成 [CSS](#模版CSS样式) 样式，生成的样式会自动作用于各自对应的区域。
139+
140+
```ts
141+
import type { ArticleModuleTemplate } from '@/types'
142+
143+
export const demoTemplate: ArticleModuleTemplate = {
144+
// 大标题区域
145+
hero: {
146+
container: {},
147+
title: {},
148+
content: {},
149+
},
150+
// 一级标题区域
151+
main: {
152+
container: {},
153+
title: {},
154+
content: {},
155+
},
156+
// 二级标题区域
157+
sub: {
158+
container: {},
159+
title: {},
160+
content: {},
161+
},
162+
}
163+
```
164+
165+
### 编写颜色主题
166+
167+
每个模版可以有很多颜色主题，项目使用 [CSS 自定义变量](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)实现颜色主题的切换。
168+
169+
CSS自定义变量使用驼峰命名方式：
170+
171+
```ts
172+
import type { ThemeConfig } from '@/types'
173+
export const demoBlue: ThemeConfig = {
174+
hero: {
175+
container: {
176+
background: '#e3dceb',
177+
backgroundImageLeft: 'url(/images/cartoon-star-left.svg)',
178+
foreground: '#000',
179+
},
180+
title: {
181+
foreground: '#fff',
182+
background: 'transparent',
183+
},
184+
content: {
185+
background: 'transparent',
186+
},
187+
},
188+
main: {
189+
container: {
190+
foreground: '#000',
191+
background: '#e3dceb',
192+
},
193+
title: {
194+
backgroundPrimary: '#ffe36c',
195+
backgroundSecondary: '#c0a1f1',
196+
},
197+
content: {
198+
background: '#fff',
199+
},
200+
},
201+
sub: {
202+
container: {},
203+
title: {
204+
background: '#ffe36c',
205+
},
206+
content: {},
207+
},
208+
}
209+
```
210+
211+
[generateThemeVariables](https://github.com/byodian/oneimg/blob/main/src/lib/template.ts#L67) 可以将 `demo-color-variables.ts` 中的内容转换为下面的格式，并使用 tss-react 的 `<GlobalStyles styles={{ ':root': cssVariables }} />` 自动插入到全局样式中。
212+
213+
```css
214+
:root {
215+
--hero-container-background: #e3dceb;
216+
--hero-container-background-image-left: url(/images/cartoon-star-left.svg);
217+
--hero-container-foreground: #000;
218+
--hero-title-foreground: #fff;
219+
--hero-title-background: transparent;
220+
--hero-content-background: transparent;
221+
--main-container-foreground: #000;
222+
--main-container-background: #e3dceb;
223+
--main-title-background-primary: #ffe36c;
224+
--main-title-background-secondary: #c0a1f1;
225+
--main-content-background: #fff;
226+
--sub-title-background: #ffe36c;
227+
}
228+
```
229+
230+
在编写模版样式的时候，你可以在 color、background 等属性中使用这些变量，比如更新 `demo-templagte.ts` 文件：
231+
232+
```ts
233+
import type { ArticleModuleTemplate } from '@/types'
234+
235+
export const demoTemplate: ArticleModuleTemplate = {
236+
// 大标题区域
237+
hero: {
238+
container: {
239+
color: 'var(--hero-container-foreground)',
240+
backgroundColor: 'var(--hero-container-background)',
241+
backgroundImage: 'var(--hero-container-background-image-left)',
242+
},
243+
title: {
244+
color: 'var(--hero-title-foreground)',
245+
backgroundColor: 'var(--hero-title-background)',
246+
},
247+
content: {
248+
backgroundColor: 'var(--hero-content-background)',
249+
},
250+
},
251+
// 一级标题区域
252+
main: {
253+
container: {
254+
color: 'var(--main-container-foreground)',
255+
backgroundColor: 'var(--main-container-background)',
256+
},
257+
title: {
258+
backgroundColor: 'var(--main-title-background-primary)',
259+
},
260+
content: {
261+
backgroundColor: 'var(--main-content-background)',
262+
},
263+
},
264+
// 二级标题区域
265+
sub: {
266+
container: {},
267+
title: {
268+
backgroundColor: 'var(--sub-title-background)',
269+
},
270+
content: {},
271+
},
272+
}
273+
```
274+
275+
### 配置模版变量
276+
模版和颜色主题编写完成后，需要在 [src/theme/index.ts](https://github.com/byodian/oneimg/blob/main/src/theme/index.ts) 文件中引入。
277+
278+
```ts
279+
import {
280+
demoBlue,
281+
demoTemplate,
282+
} from './templates'
283+
284+
// 引入模版
285+
// `value`: *模版标识*
286+
export const DEFAULT_TEMPLATES = [
287+
{ label: 'demo模版', value: 'demo-style', disabled: false, template: demoTemplate },
288+
// ...
289+
] as const
290+
291+
// 引入模版颜色主题
292+
// DEFAULT_THEME_COLOR_MAP 所有的 keys 必须和对应*模版标识*一致
293+
// `value` 为模版主题色
294+
export const DEFAULT_THEME_COLOR_MAP: Record<string, ThemeColorItem[]> = {
295+
'demo-style': [
296+
{ value: '#f14040', label: 'rose_red', theme: demoBlue },
297+
// ... 更多颜色主题
298+
],
299+
}
300+
```
301+

0 commit comments

Comments
 (0)