From b8c2294f432c72920129697f257327a8b76d6811 Mon Sep 17 00:00:00 2001 From: "ext.liuweijian3" Date: Mon, 22 Sep 2025 20:05:55 +0800 Subject: [PATCH] =?UTF-8?q?fix(ascf):=20ascf=E8=B5=84=E6=96=99=E8=B0=83?= =?UTF-8?q?=E6=95=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/GETTING-STARTED.md | 81 +++++++++++-------- versioned_docs/version-3.x/GETTING-STARTED.md | 43 ++++++++-- 2 files changed, 84 insertions(+), 40 deletions(-) diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index b39bda90a772..80c31987d818 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -753,18 +753,18 @@ $ npx taro build --type harmony-hybrid - 把 Taro 项目目录下的 `dist` 目录的编译产物复制到鸿蒙应用的 `src/main/resources/rawfile` 目录下，编译运行鸿蒙应用进行开发调试。 -### ASCF元服务 +### ASCF 元服务 -若需将 Taro 代码编译为 ASCF 元服务，需在编译命令中指定平台参数为 `ascf`，并确保满足以下条件： -- 代码中需包含 ASCF 元服务编译条件：`"ascf"`（需在项目配置中声明）。 -- 配置文件 `project.ascf.json` 需存在于项目根目录。 +若需将 Taro 代码编译为 ASCF 元服务，需在编译命令中指定平台参数为 `ascf`，并确保满足以下条件： + +- 代码中需包含 ASCF 元服务编译条件：`"ascf"`（需在项目配置中声明）。 -示例命令： -```bash -taro build --type ascf #### 编译命令 +```bash +taro build --type ascf + # pnpm $ pnpm dev:ascf $ pnpm build:ascf @@ -789,47 +789,58 @@ $ npx taro build --type ascf $ set NODE_ENV=production && taro build --type ascf --watch # CMD $ NODE_ENV=production taro build --type ascf --watch # Bash - ``` -开发者工具 +#### 开发者工具 工具准备： -下载并安装 鸿蒙开发者工具，确保已配置ASCF元服务开发环境。 -导入项目： -打开鸿蒙开发者工具，选择 导入项目。 -选择项目根目录下的 dist/ascf 目录（需确保已通过编译命令生成）。 -配置校验： -确认项目中存在 project.ascf.json 文件（元服务专属配置）。 -检查配置文件字段是否符合规范（如 minPlatformVersion、permissions 等）。 -注意事项 - -在开发者工具中需设置： +下载并安装 鸿蒙元服务 ASCF 项目[开发环境搭建指南](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/ascf-development-process)，确保已配置 ASCF 元服务开发环境。 -关闭 ES6 转 ES5 功能（开启可能导致语法错误）。 -关闭 上传代码时样式自动补全（开启可能引发样式异常）。 -关闭 代码压缩上传（开启可能影响调试信息）。 +在 taro 项目根目录下创建 ascf-project 目录，并使用工具在该目录下创建 ASCF 元服务项目。 -格式说明 +修改 taro 项目下 config/index.{js,ts}配置文件，编译 ASCF 项目情况下将 outputRoot: 'dist/ascf' 修改为 outputRoot: process.env.TARO_ENV === 'ascf' ? 'ascf-project/ascf/ascf_src' : 'dist'。 编译命令： 使用 --type ascf 指定平台类型，与其他小程序（如 --type weapp）格式统一。 支持 dev:ascf（开发模式）和 build:ascf（生产模式）。 -开发者工具： -明确指向编译后的 dist/ascf 目录，与微信小程序的 dist 目录逻辑一致。 -强调 project.ascf.json 为必需配置文件（类比 project.swan.json）。 -注意事项： -与其他小程序保持完全一致的关闭选项，避免开发者混淆。 -效果验证 +调试运行： +编译后文件在 ascf-project/ascf/ascf_src 目录下。参考鸿蒙元服务 ASCF 项目[开发流程](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/ascf-development-process) 调试运行 ascf-project 项目。如果运行有异常，可以参考[调试指南](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/debug-ascf-code)解决。 -执行编译命令后，检查 dist/ascf 目录是否包含以下文件： -manifest.json（元服务描述文件） -页面代码及资源文件 -在鸿蒙开发者工具中运行项目，确保： -页面渲染正常，无白屏或报错。 -声明的权限（如定位、相机）可正常触发弹窗申请。 +#### 适配问题 +- ASCF的app.json配置还不支持theme变量，需要适配修改为具体的值： +```javascript +{ + window: { + backgroundColorTop: '@bgColorTop', + backgroundColorBottom: '@bgColorBottom', + backgroundTextStyle: '@bgTxtStyle', + navigationBarBackgroundColor: '@navBgColor', + navigationBarTitleText: 'ascf', + navigationBarTextStyle: '@navTxtStyle' + } +} +``` +改为： + +```javascript +const theme = require('./theme.json'); +const $t = (key) => process.env.TARO_ENV === 'ascf' ? theme.light[key.replace('@', '')] : key; + +defineAppConfig({ + { + window: { + backgroundColorTop: $t('@bgColorTop'), + backgroundColorBottom: $t('@bgColorBottom'), + backgroundTextStyle: $t('@bgTxtStyle'), + navigationBarBackgroundColor: $t('@navBgColor'), + navigationBarTitleText: 'ascf', + navigationBarTextStyle: $t('@navTxtStyle') + } + } +}) +``` ## 渐进式入门教程 diff --git a/versioned_docs/version-3.x/GETTING-STARTED.md b/versioned_docs/version-3.x/GETTING-STARTED.md index 26bd5bf63e74..36d93ca81bbe 100644 --- a/versioned_docs/version-3.x/GETTING-STARTED.md +++ b/versioned_docs/version-3.x/GETTING-STARTED.md @@ -713,13 +713,12 @@ $ npx taro build --type harmony-hybrid - 代码中需包含 ASCF 元服务编译条件：`"ascf"`（需在项目配置中声明）。 -示例命令： + +#### 编译命令 ```bash taro build --type ascf -#### 编译命令 - # pnpm $ pnpm dev:ascf $ pnpm build:ascf @@ -744,10 +743,9 @@ $ npx taro build --type ascf $ set NODE_ENV=production && taro build --type ascf --watch # CMD $ NODE_ENV=production taro build --type ascf --watch # Bash - ``` -开发者工具 +#### 开发者工具 工具准备： 下载并安装 鸿蒙元服务 ASCF 项目[开发环境搭建指南](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/ascf-development-process)，确保已配置 ASCF 元服务开发环境。 @@ -763,6 +761,41 @@ $ NODE_ENV=production taro build --type ascf --watch # Bash 调试运行： 编译后文件在 ascf-project/ascf/ascf_src 目录下。参考鸿蒙元服务 ASCF 项目[开发流程](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/ascf-development-process) 调试运行 ascf-project 项目。如果运行有异常，可以参考[调试指南](https://developer.huawei.com/consumer/cn/doc/atomic-ascf/debug-ascf-code)解决。 +#### 适配问题 + +- ASCF的app.json配置还不支持theme变量，需要适配修改为具体的值： +```javascript +{ + window: { + backgroundColorTop: '@bgColorTop', + backgroundColorBottom: '@bgColorBottom', + backgroundTextStyle: '@bgTxtStyle', + navigationBarBackgroundColor: '@navBgColor', + navigationBarTitleText: 'ascf', + navigationBarTextStyle: '@navTxtStyle' + } +} +``` +改为： + +```javascript +const theme = require('./theme.json'); +const $t = (key) => process.env.TARO_ENV === 'ascf' ? theme.light[key.replace('@', '')] : key; + +defineAppConfig({ + { + window: { + backgroundColorTop: $t('@bgColorTop'), + backgroundColorBottom: $t('@bgColorBottom'), + backgroundTextStyle: $t('@bgTxtStyle'), + navigationBarBackgroundColor: $t('@navBgColor'), + navigationBarTitleText: 'ascf', + navigationBarTextStyle: $t('@navTxtStyle') + } + } +}) +``` + ## 渐进式入门教程 我们提供了一个由浅入深的实战教程，请参考[《教程》](./guide)。