Skip to content

Commit cbca3af

Browse files
ienagaienaga
committed
#162 ドキュメントのアップデート
1 parent 063764a commit cbca3af

3 files changed

Lines changed: 294 additions & 174 deletions

File tree

‎specs/cn/config.md‎

Lines changed: 99 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,11 @@ src/config/
1111
└── routing.json # 路由设置
1212
```
1313

14+
---
15+
1416
## stage.json
1517

16-
用于设置显示区域（Stage）的 JSON 文件。
18+
用于配置显示区域（Stage）的 JSON 文件。应用启动时读取一次，作为 Stage 的初始参数使用。
1719

1820
```json
1921
{
@@ -32,22 +34,30 @@ src/config/
3234

3335
| 属性 | 类型 | 默认值 | 说明 |
3436
|------|------|--------|------|
35-
| `width` | number | 240 | 显示区域宽度 |
36-
| `height` | number | 240 | 显示区域高度 |
37-
| `fps` | number | 60 | 每秒绘制次数（1-60） |
38-
| `options` | object | null | 选项设置 |
37+
| `width` | number | 240 | 显示区域宽度（像素）。作为渲染画布的基准宽度使用 |
38+
| `height` | number | 240 | 显示区域高度（像素）。作为渲染画布的基准高度使用 |
39+
| `fps` | number | 60 | 每秒渲染次数。有效范围为 1〜60 |
40+
| `options` | object | null | 附加选项设置。可省略 |
3941

4042
### options 设置
4143

4244
| 属性 | 类型 | 默认值 | 说明 |
4345
|------|------|--------|------|
44-
| `fullScreen` | boolean | false | 超出舞台宽高在整个屏幕上绘制 |
45-
| `tagId` | string | null | 指定后，绘制发生在具有该 ID 的元素内 |
46-
| `bgColor` | string | "transparent" | 十六进制背景颜色。默认为透明 |
46+
| `fullScreen` | boolean | false | 设为 `true` 时，Stage 扩展为填充整个窗口。设为 `false` 时，以 `width`・`height` 指定的尺寸固定渲染 |
47+
| `tagId` | string \| null | null | 用作渲染目标的 HTML 元素 ID。画布在指定 ID 的元素内部创建。为 `null` 时直接在 `<body>` 下创建 |
48+
| `bgColor` | string | "transparent" | 以十六进制颜色代码指定背景色（例：`"#1461A0"`）。指定 `"transparent"` 则为透明 |
49+
50+
> [!WARNING]
51+
> `stage.json` 中有效的属性仅有 `width`・`height`・`fps`・`options`。
52+
> `align`・`scaleMode` 等与 Stage 显示相关的设置，在 `stage.json` 中并不存在。
53+
> 如需这些设置，请在 `config.json` 中定义。
54+
> 上述以外的属性将被框架完全忽略，不做任何处理。
55+
56+
---
4757

4858
## config.json
4959

50-
用于管理特定环境设置的文件。分为 `local`、`dev`、`stg`、`prd` 和 `all`，其中除 `all` 以外的任何环境名称都是任意的。
60+
用于管理各环境设置的文件。构建时，与 `--env` 选项指定的环境名匹配的对象和 `all` 对象合并后，作为整个应用可引用的设置展开。
5161

5262
```json
5363
{
@@ -82,31 +92,81 @@ src/config/
8292
}
8393
```
8494

85-
### all 设置
95+
### 环境键规格
96+
97+
`local`・`dev`・`stg`・`prd` 等键名可任意指定（`all` 除外）。构建时，与 `--env=<环境名>` 匹配的键的对象将被读取。
8698

87-
`all` 是在任何环境中导出的公共变量。
99+
| 键 | 说明 |
100+
|----|------|
101+
| `all` | 在所有环境下均会读取的公共设置 |
102+
| 其他 | 仅在键名与构建时 `--env` 指定值匹配时读取的设置 |
103+
104+
### all 设置（框架保留属性）
105+
106+
以下属性由框架自动处理。
88107

89108
| 属性 | 类型 | 默认值 | 说明 |
90109
|------|------|--------|------|
91-
| `spa` | boolean | true | 作为单页应用程序通过 URL 控制场景 |
92-
| `defaultTop` | string | "top" | 页面顶部的 View。如果未设置，将启动 TopView 类 |
93-
| `loading.callback` | string | Loading | 加载画面类名。调用 start 和 end 函数 |
94-
| `gotoView.callback` | string \| array | ["callback.Background"] | gotoView 完成后的回调类 |
110+
| `spa` | boolean | true | 设为 `true` 时，作为单页应用程序运行，与浏览器 URL 联动管理 View 切换 |
111+
| `defaultTop` | string | "top" | 应用启动时最先显示的 View 名称。未指定时启动 `TopView` 类 |
112+
| `loading.callback` | string | "Loading" | 用作加载画面的类名。该类的 `start()` 和 `end()` 会被自动调用 |
113+
| `gotoView.callback` | string \| string[] | — | View 切换完成后调用的回调类名。可以数组形式指定多个，按 async/await 顺序执行 |
114+
115+
### 用户自定义属性
116+
117+
除框架保留属性外，可在任意环境键中添加任意属性。添加的属性在构建后可通过 `config` 对象引用。
118+
119+
端点 URL、功能开关、显示设置等需要按环境区分的值，可在此处统一管理。
120+
121+
```json
122+
{
123+
"local": {
124+
"api": {
125+
"endPoint": "http://localhost:3000/"
126+
}
127+
},
128+
"prd": {
129+
"api": {
130+
"endPoint": "https://api.example.com/"
131+
}
132+
},
133+
"all": {
134+
"spa": true,
135+
"defaultTop": "top",
136+
"align": "TL",
137+
"scaleMode": "noScale"
138+
}
139+
}
140+
```
141+
142+
```typescript
143+
import { config } from "@/config/Config";
144+
145+
// 访问用户自定义属性
146+
const align = config.align; // "TL"
147+
const scaleMode = config.scaleMode; // "noScale"
148+
```
149+
150+
> [!WARNING]
151+
> `config.json` 中框架自动处理的属性仅有 `spa`・`defaultTop`・`loading`・`gotoView`。
152+
> 其他属性不会被框架直接处理，但可通过 `config` 对象在应用代码中自由引用。
95153
96154
### platform 设置
97155

98-
构建时使用 `--platform` 指定的值会被设置。
156+
构建时通过 `--platform` 指定的值会被自动设置。无需在配置文件中填写，为只读项。
99157

100158
支持的值：`macos`、`windows`、`linux`、`ios`、`android`、`web`
101159

102160
```typescript
103161
import { config } from "@/config/Config";
104162

105163
if (config.platform === "ios") {
106-
// iOS 特定处理
164+
// iOS 专用处理
107165
}
108166
```
109167

168+
---
169+
110170
## routing.json
111171

112172
路由配置文件。详情请参阅[路由](/cn/reference/framework/routing)。
@@ -128,53 +188,21 @@ if (config.platform === "ios") {
128188
}
129189
```
130190

131-
## 获取配置值
132-
133-
在代码中使用 `config` 对象获取配置值。
134-
135-
### Config.ts 示例
191+
---
136192

137-
```typescript
138-
import stageJson from "./stage.json";
139-
import configJson from "./config.json";
140-
141-
interface IStageConfig {
142-
width: number;
143-
height: number;
144-
fps: number;
145-
options: {
146-
fullScreen: boolean;
147-
tagId: string | null;
148-
bgColor: string;
149-
};
150-
}
193+
## 获取配置值
151194

152-
interface IConfig {
153-
stage: IStageConfig;
154-
api: {
155-
endPoint: string;
156-
};
157-
content: {
158-
endPoint: string;
159-
};
160-
spa: boolean;
161-
defaultTop: string;
162-
platform: string;
163-
}
195+
`Config.ts` 是执行 `npm start` 时自动生成的文件，无需手动创建或编辑。
164196

165-
export const config: IConfig = {
166-
stage: stageJson,
167-
...configJson
168-
};
169-
```
197+
在代码中通过导入自动生成的 `config` 对象来获取配置值。
170198

171199
### 使用示例
172200

173201
```typescript
174202
import { config } from "@/config/Config";
175203

176-
// 舞台设置
177-
const stageWidth = config.stage.width;
204+
// Stage 设置
205+
const stageWidth = config.stage.width;
178206
const stageHeight = config.stage.height;
179207

180208
// API 设置
@@ -184,9 +212,11 @@ const apiEndPoint = config.api.endPoint;
184212
const isSpa = config.spa;
185213
```
186214

215+
---
216+
187217
## 加载画面
188218

189-
调用 `loading.callback` 中设置的类的 `start` 和 `end` 函数。
219+
`loading.callback` 中设置的类的 `start()` 和 `end()` 方法会被自动调用。
190220

191221
```typescript
192222
export class Loading
@@ -213,9 +243,11 @@ export class Loading
213243
}
214244
```
215245

246+
---
247+
216248
## gotoView 回调
217249

218-
调用 `gotoView.callback` 中设置的类的 `execute` 函数。可以设置多个类作为数组，并使用 async/await 顺序执行。
250+
`gotoView.callback` 中设置的类的 `execute()` 方法会被调用。可以数组形式指定多个类，按 async/await 顺序执行。
219251

220252
```typescript
221253
import { app } from "@next2d/framework";
@@ -236,12 +268,14 @@ export class Background
236268
const view = context.view;
237269
if (!view) return;
238270

239-
// 将背景放在后面
271+
// 将背景放置在最底层
240272
view.addChildAt(this.shape, 0);
241273
}
242274
}
243275
```
244276

277+
---
278+
245279
## 构建命令
246280

247281
带环境指定的构建：
@@ -265,6 +299,8 @@ npm run build -- --platform=ios
265299
npm run build -- --platform=android
266300
```
267301

302+
---
303+
268304
## 配置示例
269305

270306
### 完整配置文件示例
@@ -320,11 +356,15 @@ npm run build -- --platform=android
320356
},
321357
"gotoView": {
322358
"callback": ["callback.Background"]
323-
}
359+
},
360+
"align": "TL",
361+
"scaleMode": "noScale"
324362
}
325363
}
326364
```
327365

366+
---
367+
328368
## 相关
329369

330370
- [路由](/cn/reference/framework/routing)

0 commit comments

Comments
 (0)