diff --git a/docs/cn/reference/framework/config/index.html b/docs/cn/reference/framework/config/index.html index 1a934dde..48018e48 100644 --- a/docs/cn/reference/framework/config/index.html +++ b/docs/cn/reference/framework/config/index.html @@ -11,8 +11,9 @@

文件结构

├── stage.json # 显示区域设置 ├── config.json # 环境设置 └── routing.json # 路由设置 +

stage.json

-

用于设置显示区域（Stage）的 JSON 文件。

+

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

{
     "width": 1920,
     "height": 1080,
@@ -59,7 +60,7 @@ 
属性

 
 
 
-
属性类型默认值说明
widthnumber240显示区域宽度
heightnumber240显示区域高度
fpsnumber60每秒绘制次数（1-60）
optionsobjectnull选项设置

+
属性类型默认值说明
widthnumber240显示区域宽度（像素）。作为渲染画布的基准宽度使用
heightnumber240显示区域高度（像素）。作为渲染画布的基准高度使用
fpsnumber60每秒渲染次数。有效范围为 1〜60
optionsobjectnull附加选项设置。可省略

 
options 设置

 
 
@@ -90,9 +91,17 @@ 
options 设置

 
 
 
-
属性类型默认值说明
fullScreenbooleanfalse超出舞台宽高在整个屏幕上绘制
tagIdstringnull指定后，绘制发生在具有该 ID 的元素内
bgColorstring”transparent”十六进制背景颜色。默认为透明

+
属性类型默认值说明
fullScreenbooleanfalse设为 true 时，Stage 扩展为填充整个窗口。设为 false 时，以 width・height 指定的尺寸固定渲染
tagIdstring | nullnull用作渲染目标的 HTML 元素 ID。画布在指定 ID 的元素内部创建。为 null 时直接在 <body> 下创建
bgColorstring”transparent”以十六进制颜色代码指定背景色（例："#1461A0"）。指定 "transparent" 则为透明

+

+
[!WARNING]
+stage.json 中有效的属性仅有 width・height・fps・options。
+align・scaleMode 等与 Stage 显示相关的设置，在 stage.json 中并不存在。
+如需这些设置，请在 config.json 中定义。
+上述以外的属性将被框架完全忽略，不做任何处理。

+

+

 
config.json

-
用于管理特定环境设置的文件。分为 local、dev、stg、prd 和 all，其中除 all 以外的任何环境名称都是任意的。

+
用于管理各环境设置的文件。构建时，与 --env 选项指定的环境名匹配的对象和 all 对象合并后，作为整个应用可引用的设置展开。

 
{
     "local": {
         "api": {
@@ -123,8 +132,8 @@ 
config.json

         }
     }
 }

-
all 设置

-
all 是在任何环境中导出的公共变量。

+
环境键规格

+
local・dev・stg・prd 等键名可任意指定（all 除外）。构建时，与 --env=<环境名> 匹配的键的对象将被读取。

 
 
 
@@ -142,6 +151,9 @@ 
all 设置

 
 
 
+
键说明
all在所有环境下均会读取的公共设置
其他仅在键名与构建时 --env 指定值匹配时读取的设置

+
all 设置（框架保留属性）

+
以下属性由框架自动处理。

 
 
 
@@ -160,15 +172,64 @@ 
all 设置

 
 
 
-
属性类型默认值说明
spabooleantrue作为单页应用程序通过 URL 控制场景
defaultTopstring”top”页面顶部的 View。如果未设置，将启动 TopView 类
loading.callbackstringLoading加载画面类名。调用 start 和 end 函数
gotoView.callbackstring | array[“callback.Background”]gotoView 完成后的回调类

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
属性类型默认值说明
spabooleantrue设为 true 时，作为单页应用程序运行，与浏览器 URL 联动管理 View 切换
defaultTopstring”top”应用启动时最先显示的 View 名称。未指定时启动 TopView 类
loading.callbackstring”Loading”用作加载画面的类名。该类的 start() 和 end() 会被自动调用
gotoView.callbackstring | string[]—View 切换完成后调用的回调类名。可以数组形式指定多个，按 async/await 顺序执行

+
用户自定义属性

+
除框架保留属性外，可在任意环境键中添加任意属性。添加的属性在构建后可通过 config 对象引用。

+
端点 URL、功能开关、显示设置等需要按环境区分的值，可在此处统一管理。

+
{
+    "local": {
+        "api": {
+            "endPoint": "http://localhost:3000/"
+        }
+    },
+    "prd": {
+        "api": {
+            "endPoint": "https://api.example.com/"
+        }
+    },
+    "all": {
+        "spa": true,
+        "defaultTop": "top",
+        "align": "TL",
+        "scaleMode": "noScale"
+    }
+}

+
import { config } from "@/config/Config";
+
+// 访问用户自定义属性
+const align     = config.align;     // "TL"
+const scaleMode = config.scaleMode; // "noScale"

+

+
[!WARNING]
+config.json 中框架自动处理的属性仅有 spa・defaultTop・loading・gotoView。
+其他属性不会被框架直接处理，但可通过 config 对象在应用代码中自由引用。

+

 
platform 设置

-
构建时使用 --platform 指定的值会被设置。

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

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

 
import { config } from "@/config/Config";
 
 if (config.platform === "ios") {
-    // iOS 特定处理
+    // iOS 专用处理
 }

+

 
routing.json

 
路由配置文件。详情请参阅路由。

 
{
@@ -185,45 +246,15 @@ 
routing.json

         "requests": []
     }
 }

+

 
获取配置值

-
在代码中使用 config 对象获取配置值。

-
Config.ts 示例

-
import stageJson from "./stage.json";
-import configJson from "./config.json";
-
-interface IStageConfig {
-    width: number;
-    height: number;
-    fps: number;
-    options: {
-        fullScreen: boolean;
-        tagId: string | null;
-        bgColor: string;
-    };
-}
-
-interface IConfig {
-    stage: IStageConfig;
-    api: {
-        endPoint: string;
-    };
-    content: {
-        endPoint: string;
-    };
-    spa: boolean;
-    defaultTop: string;
-    platform: string;
-}
-
-export const config: IConfig = {
-    stage: stageJson,
-    ...configJson
-};

+
Config.ts 是执行 npm start 时自动生成的文件，无需手动创建或编辑。

+
在代码中通过导入自动生成的 config 对象来获取配置值。

 
使用示例

 
import { config } from "@/config/Config";
 
-// 舞台设置
-const stageWidth = config.stage.width;
+// Stage 设置
+const stageWidth  = config.stage.width;
 const stageHeight = config.stage.height;
 
 // API 设置
@@ -231,8 +262,9 @@ 
使用示例

 
 // SPA 设置
 const isSpa = config.spa;

+

 
加载画面

-
调用 loading.callback 中设置的类的 start 和 end 函数。

+
loading.callback 中设置的类的 start() 和 end() 方法会被自动调用。

 
export class Loading
 {
     private shape: Shape;
@@ -255,8 +287,9 @@ 
加载画面

         this.shape.remove();
     }
 }

+

 
gotoView 回调

-
调用 gotoView.callback 中设置的类的 execute 函数。可以设置多个类作为数组，并使用 async/await 顺序执行。

+
gotoView.callback 中设置的类的 execute() 方法会被调用。可以数组形式指定多个类，按 async/await 顺序执行。

 
import { app } from "@next2d/framework";
 import { Shape, stage } from "@next2d/display";
 
@@ -275,10 +308,11 @@ 
gotoView 回调

         const view = context.view;
         if (!view) return;
 
-        // 将背景放在后面
+        // 将背景放置在最底层
         view.addChildAt(this.shape, 0);
     }
 }

+

 
构建命令

 
带环境指定的构建：

 
# 本地环境
@@ -293,6 +327,7 @@ 
构建命令

 
npm run build -- --platform=web
 npm run build -- --platform=ios
 npm run build -- --platform=android

+

 
配置示例

 
完整配置文件示例

 
stage.json

@@ -340,9 +375,12 @@ 
config.json

         },
         "gotoView": {
             "callback": ["callback.Background"]
-        }
+        },
+        "align": "TL",
+        "scaleMode": "noScale"
     }
 }

+

 
相关
+

stage.json

-

JSON file for setting the display area (Stage).

+

JSON file for configuring the display area (Stage). It is read once at application startup and used as the initial parameters for the Stage.

{
     "width": 1920,
     "height": 1080,
@@ -59,7 +60,7 @@ 
Properties

 
 
 
-
PropertyTypeDefaultDescription
widthnumber240Display area width
heightnumber240Display area height
fpsnumber60Drawings per second (1-60)
optionsobjectnullOption settings

+
PropertyTypeDefaultDescription
widthnumber240Display area width in pixels. Used as the base width of the rendering canvas
heightnumber240Display area height in pixels. Used as the base height of the rendering canvas
fpsnumber60Number of renders per second. Valid range is 1–60
optionsobjectnullAdditional option settings. Can be omitted

 
options Settings

 
 
@@ -90,9 +91,17 @@ 
options Settings

 
 
 
-
PropertyTypeDefaultDescription
fullScreenbooleanfalseDraw on entire screen beyond Stage width/height
tagIdstringnullWhen specified, drawing occurs within the element with that ID
bgColorstring”transparent”Background color in hexadecimal. Default is transparent

+
PropertyTypeDefaultDescription
fullScreenbooleanfalseWhen true, the Stage expands to fill the entire window. When false, rendering is fixed to the size specified by width and height
tagIdstring | nullnullID of the HTML element to use as the rendering target. The canvas is created inside the element with the specified ID. When null, the canvas is created directly under <body>
bgColorstring”transparent”Background color as a hexadecimal color code (e.g. "#1461A0"). Use "transparent" for a transparent background

+

+
[!WARNING]
+The only valid properties in stage.json are width, height, fps, and options.
+Properties such as align and scaleMode — even though they relate to Stage display — do not exist in stage.json.
+If you need these settings, define them in config.json.
+Any properties not listed above are completely ignored by the framework.

+

+

 
config.json

-
File for managing environment-specific settings. Divided into local, dev, stg, prd, and all, where any environment name except all is arbitrary.

+
File for managing environment-specific settings. At build time, the object matching the environment name specified with --env is merged with the all object and made available throughout the application.

 
{
     "local": {
         "api": {
@@ -123,8 +132,8 @@ 
config.json

         }
     }
 }

-
all Settings

-
all is a common variable exported in any environment.

+
Environment Key Specification

+
Key names such as local, dev, stg, and prd are arbitrary (except all). The object whose key matches --env=<environment> at build time is loaded.

 
 
 
@@ -142,6 +151,9 @@ 
all Settings

 
 
 
+
KeyDescription
allSettings loaded in all environments
OthersSettings loaded only when the key matches the --env value at build time

+
all Settings (Framework Reserved Properties)

+
The following properties are automatically processed by the framework.

 
 
 
@@ -160,15 +172,64 @@ 
all Settings

 
 
 
-
PropertyTypeDefaultDescription
spabooleantrueControl scenes via URL as Single Page Application
defaultTopstring”top”View for page top. TopView class launches if not set
loading.callbackstringLoadingLoading screen class name. Calls start and end functions
gotoView.callbackstring | array[“callback.Background”]Callback class after gotoView completion

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
PropertyTypeDefaultDescription
spabooleantrueWhen true, the application behaves as a Single Page Application and manages View transitions in sync with the browser URL
defaultTopstring”top”Name of the View to display first when the application starts. If not specified, the TopView class is launched
loading.callbackstring”Loading”Class name to use as the loading screen. The class’s start() and end() methods are called automatically
gotoView.callbackstring | string[]—Callback class name(s) to call after a View transition completes. Multiple classes can be specified as an array and are executed sequentially with async/await

+
User-Defined Properties

+
In addition to the framework reserved properties, you can add any properties to any environment key. Added properties are accessible from the config object after the build.

+
Use this to manage values that need to differ per environment, such as endpoint URLs, feature flags, and display settings.

+
{
+    "local": {
+        "api": {
+            "endPoint": "http://localhost:3000/"
+        }
+    },
+    "prd": {
+        "api": {
+            "endPoint": "https://api.example.com/"
+        }
+    },
+    "all": {
+        "spa": true,
+        "defaultTop": "top",
+        "align": "TL",
+        "scaleMode": "noScale"
+    }
+}

+
import { config } from "@/config/Config";
+
+// Accessing user-defined properties
+const align     = config.align;     // "TL"
+const scaleMode = config.scaleMode; // "noScale"

+

+
[!WARNING]
+The only properties automatically processed by the framework in config.json are spa, defaultTop, loading, and gotoView.
+All other properties are not processed directly by the framework, but can be freely accessed from application code via the config object.

+

 
platform Settings

-
The value specified with --platform at build time is set.

+
The value specified with --platform at build time is automatically set. It does not need to be written in the configuration file and is read-only.

 
Supported values: macos, windows, linux, ios, android, web

 
import { config } from "@/config/Config";
 
 if (config.platform === "ios") {
     // iOS-specific processing
 }

+

 
routing.json

 
Routing configuration file. See Routing for details.

 
{
@@ -185,45 +246,15 @@ 
routing.json

         "requests": []
     }
 }

+

 
Getting Configuration Values

-
Use the config object to get configuration values in code.

-
Config.ts Example

-
import stageJson from "./stage.json";
-import configJson from "./config.json";
-
-interface IStageConfig {
-    width: number;
-    height: number;
-    fps: number;
-    options: {
-        fullScreen: boolean;
-        tagId: string | null;
-        bgColor: string;
-    };
-}
-
-interface IConfig {
-    stage: IStageConfig;
-    api: {
-        endPoint: string;
-    };
-    content: {
-        endPoint: string;
-    };
-    spa: boolean;
-    defaultTop: string;
-    platform: string;
-}
-
-export const config: IConfig = {
-    stage: stageJson,
-    ...configJson
-};

+
Config.ts is auto-generated when running npm start. You do not need to create or edit it manually.

+
To get configuration values in code, import and use the auto-generated config object.

 
Usage Example

 
import { config } from "@/config/Config";
 
 // Stage settings
-const stageWidth = config.stage.width;
+const stageWidth  = config.stage.width;
 const stageHeight = config.stage.height;
 
 // API settings
@@ -231,8 +262,9 @@ 
Usage Example

 
 // SPA setting
 const isSpa = config.spa;

+

 
Loading Screen

-
The start and end functions of the class set in loading.callback are called.

+
The start() and end() methods of the class set in loading.callback are called automatically.

 
export class Loading
 {
     private shape: Shape;
@@ -255,8 +287,9 @@ 
Loading Screen

         this.shape.remove();
     }
 }

+

 
gotoView Callback

-
The execute function of classes set in gotoView.callback is called. Multiple classes can be set as an array and executed sequentially with async/await.

+
The execute() method of classes set in gotoView.callback is called. Multiple classes can be specified as an array and are executed sequentially with async/await.

 
import { app } from "@next2d/framework";
 import { Shape, stage } from "@next2d/display";
 
@@ -279,6 +312,7 @@ 
gotoView Callback

         view.addChildAt(this.shape, 0);
     }
 }

+

 
Build Commands

 
Build with environment specification:

 
# Local environment
@@ -293,6 +327,7 @@ 
Build Commands

 
npm run build -- --platform=web
 npm run build -- --platform=ios
 npm run build -- --platform=android

+

 
Configuration Examples

 
Complete Configuration File Examples

 
stage.json

@@ -340,9 +375,12 @@ 
config.json

         },
         "gotoView": {
             "callback": ["callback.Background"]
-        }
+        },
+        "align": "TL",
+        "scaleMode": "noScale"
     }
 }

+
+

stage.json

-

表示領域（Stage）の設定を行うJSONファイルです。

+

表示領域（Stage）の設定を行うJSONファイルです。アプリ起動時に一度だけ読み込まれ、Stageの初期パラメータとして使用されます。

{
     "width": 1920,
     "height": 1080,
@@ -59,8 +60,8 @@ 
プロパティ

 
 
 
-
プロパティ型デフォルト説明
widthnumber240表示領域の幅
heightnumber240表示領域の高さ
fpsnumber601秒間に何回描画するか（1〜60）
optionsobjectnullオプション設定

-
options設定

+
プロパティ型デフォルト説明
widthnumber240表示領域の幅（ピクセル単位）。実際の描画キャンバスの基準幅として使用される
heightnumber240表示領域の高さ（ピクセル単位）。実際の描画キャンバスの基準高さとして使用される
fpsnumber601秒間の描画回数。指定可能な範囲は 1〜60
optionsobjectnull追加オプション設定。省略可能

+
options 設定

 
 
 
@@ -90,9 +91,17 @@ 
options設定

 
 
 
-
プロパティ型デフォルト説明
fullScreenbooleanfalseStageで設定した幅と高さを超えて画面全体に描画
tagIdstringnullIDを指定すると、指定したIDのエレメント内で描画を行う
bgColorstring”transparent”背景色を16進数で指定。デフォルトは無色透明

+
プロパティ型デフォルト説明
fullScreenbooleanfalsetrue にするとウィンドウ全体にStageを拡張して描画する。false の場合は width・height で指定したサイズで固定描画
tagIdstring | nullnull描画先とするHTML要素のID。指定したIDのエレメント内部にキャンバスが生成される。null の場合は <body> 直下に生成される
bgColorstring”transparent”背景色を16進数カラーコードで指定（例: "#1461A0"）。"transparent" を指定すると透明になる

+

+
[!WARNING]
+stage.json で有効なプロパティは上記の width・height・fps・options のみです。
+align・scaleMode などステージ表示に関わる設定であっても、stage.json には存在しないプロパティです。
+これらの設定が必要な場合は config.json に記述してください。
+上記以外のプロパティを記述しても、フレームワークは一切処理しません。

+

+

 
config.json

-
環境ごとの設定を管理するファイルです。local、dev、stg、prd、allと区切られており、all以外は任意の環境名です。

+
環境ごとの設定を管理するファイルです。ビルド時に --env オプションで指定した環境名のオブジェクトと all オブジェクトがマージされ、アプリケーション全体で参照可能な設定として展開されます。

 
{
     "local": {
         "api": {
@@ -123,8 +132,8 @@ 
config.json

         }
     }
 }

-
all設定

-
allはどの環境でも書き出される共通変数です。

+
環境キーの仕様

+
local・dev・stg・prd などのキー名は任意です（all を除く）。ビルド時に --env=<環境名> で一致したキーのオブジェクトが読み込まれます。

 
 
 
@@ -142,6 +151,9 @@ 
all設定

 
 
 
+
キー説明
allすべての環境で共通して読み込まれる設定
それ以外--env で指定した環境名と一致したときのみ読み込まれる設定

+
all 設定（フレームワーク予約済みプロパティ）

+
以下のプロパティはフレームワークが自動的に処理します。

 
 
 
@@ -160,15 +172,64 @@ 
all設定

 
 
 
-
プロパティ型デフォルト説明
spabooleantrueSingle Page ApplicationとしてURLでシーンを制御
defaultTopstring”top”ページトップのView。設定がない場合はTopViewクラスが起動
loading.callbackstringLoadingローディング画面のクラス名。start関数とend関数を呼び出す
gotoView.callbackstring | array[“callback.Background”]gotoView完了後のコールバッククラス

-
platform設定

-
ビルド時の--platformで指定した値がセットされます。

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
プロパティ型デフォルト説明
spabooleantruetrue にするとSingle Page Applicationとして動作し、ブラウザのURLと連動してView遷移を管理する
defaultTopstring”top”アプリ起動時に最初に表示するViewの名前。指定しない場合は TopView クラスが起動する
loading.callbackstring”Loading”ローディング画面として使用するクラス名。そのクラスの start() と end() が自動的に呼び出される
gotoView.callbackstring | string[]—View遷移完了後に呼び出すコールバッククラス名。配列で複数指定でき、async/awaitで順次実行される

+
ユーザー定義プロパティ

+
フレームワークの予約済みプロパティ以外に、任意のプロパティをどの環境キーにも追加できます。追加したプロパティはビルド後に config オブジェクトから参照できます。

+
エンドポイントURLや機能フラグ、表示設定など、環境ごとに変える必要がある値をここで管理します。

+
{
+    "local": {
+        "api": {
+            "endPoint": "http://localhost:3000/"
+        }
+    },
+    "prd": {
+        "api": {
+            "endPoint": "https://api.example.com/"
+        }
+    },
+    "all": {
+        "spa": true,
+        "defaultTop": "top",
+        "align": "TL",
+        "scaleMode": "noScale"
+    }
+}

+
import { config } from "@/config/Config";
+
+// ユーザー定義プロパティへのアクセス
+const align     = config.align;     // "TL"
+const scaleMode = config.scaleMode; // "noScale"

+

+
[!WARNING]
+config.json でフレームワークが自動処理するプロパティは spa・defaultTop・loading・gotoView のみです。
+それ以外のプロパティはフレームワークが直接処理することはありませんが、config オブジェクト経由でアプリケーションコードから自由に参照できます。

+

+
platform 設定

+
ビルド時の --platform で指定した値が自動的にセットされます。設定ファイルに記述する必要はなく、読み取り専用です。

 
対応値: macos, windows, linux, ios, android, web

 
import { config } from "@/config/Config";
 
 if (config.platform === "ios") {
     // iOS固有の処理
 }

+

 
routing.json

 
ルーティングの設定ファイルです。詳細はルーティングを参照してください。

 
{
@@ -185,45 +246,15 @@ 
routing.json

         "requests": []
     }
 }

+

 
設定値の取得

-
コード内で設定値を取得するにはconfigオブジェクトを使用します。

-
Config.tsの例

-
import stageJson from "./stage.json";
-import configJson from "./config.json";
-
-interface IStageConfig {
-    width: number;
-    height: number;
-    fps: number;
-    options: {
-        fullScreen: boolean;
-        tagId: string | null;
-        bgColor: string;
-    };
-}
-
-interface IConfig {
-    stage: IStageConfig;
-    api: {
-        endPoint: string;
-    };
-    content: {
-        endPoint: string;
-    };
-    spa: boolean;
-    defaultTop: string;
-    platform: string;
-}
-
-export const config: IConfig = {
-    stage: stageJson,
-    ...configJson
-};

+
Config.ts は npm start 実行時に自動生成されるファイルです。手動で作成・編集する必要はありません。

+
コード内で設定値を取得するには、自動生成された config オブジェクトをインポートして使用します。

 
使用例

 
import { config } from "@/config/Config";
 
 // ステージ設定
-const stageWidth = config.stage.width;
+const stageWidth  = config.stage.width;
 const stageHeight = config.stage.height;
 
 // API設定
@@ -231,8 +262,9 @@ 
使用例

 
 // SPA設定
 const isSpa = config.spa;

+

 
ローディング画面

-
loading.callbackで設定したクラスのstart関数とend関数が呼び出されます。

+
loading.callback で設定したクラスの start() と end() が自動的に呼び出されます。

 
export class Loading
 {
     private shape: Shape;
@@ -255,8 +287,9 @@ 
ローディング画面

         this.shape.remove();
     }
 }

-
gotoViewコールバック

-
gotoView.callbackで設定したクラスのexecute関数が呼び出されます。複数のクラスを配列で設定でき、async/awaitで順次実行されます。

+

+
gotoView コールバック

+
gotoView.callback で設定したクラスの execute() が呼び出されます。配列で複数のクラスを指定でき、async/await で順次実行されます。

 
import { app } from "@next2d/framework";
 import { Shape, stage } from "@next2d/display";
 
@@ -279,6 +312,7 @@ 
gotoViewコールバック

         view.addChildAt(this.shape, 0);
     }
 }

+

 
ビルドコマンド

 
環境を指定してビルド:

 
# ローカル環境
@@ -293,6 +327,7 @@ 
ビルドコマンド

 
npm run build -- --platform=web
 npm run build -- --platform=ios
 npm run build -- --platform=android

+

 
設定例

 
完全な設定ファイルの例

 
stage.json

@@ -340,9 +375,12 @@ 
config.json

         },
         "gotoView": {
             "callback": ["callback.Background"]
-        }
+        },
+        "align": "TL",
+        "scaleMode": "noScale"
     }
 }

+

 
関連項目