From c164344c66d8f4fe0f347e7c33e328fee107933f Mon Sep 17 00:00:00 2001 From: wanganxp Date: Fri, 15 Dec 2023 06:49:20 +0800 Subject: [PATCH] x --- docs/api/facial-recognition-verify.md | 2 + docs/api/file-system-spec.md | 168 ++++++++++++++++++++++ docs/api/file-system.md | 112 --------------- docs/api/filemanager.md | 21 --- docs/api/get-univerify-manager.md | 3 + docs/collocation/manifest-splashscreen.md | 10 +- docs/compiler/README.md | 3 + 7 files changed, 185 insertions(+), 134 deletions(-) create mode 100644 docs/api/file-system-spec.md delete mode 100644 docs/api/file-system.md delete mode 100644 docs/api/filemanager.md diff --git a/docs/api/facial-recognition-verify.md b/docs/api/facial-recognition-verify.md index 0cc2a737..9cf9e328 100644 --- a/docs/api/facial-recognition-verify.md +++ b/docs/api/facial-recognition-verify.md @@ -7,6 +7,8 @@ uni实人认证是DCloud与合作伙伴共同推出的金融级实人认证服 2. 客户端API，即本文 3. 服务器API，[详见](https://doc.dcloud.net.cn/uniCloud/frv/dev.html) +uni-id-pages，已经内置实人认证，从云端到客户端均已开发好并开源，推荐使用。[详情](https://doc.dcloud.net.cn/uniCloud/uni-id/app-x.html) + ## uni.getFacialRecognitionMetaInfo() @getfacialrecognitionmetainfo diff --git a/docs/api/file-system-spec.md b/docs/api/file-system-spec.md new file mode 100644 index 00000000..2fbc1df1 --- /dev/null +++ b/docs/api/file-system-spec.md @@ -0,0 +1,168 @@ +# 文件系统 +文件系统提供一套跨平台操作文件的管理接口，包括文件和目录的增删改名、获取信息、读写文件等常用功能。 + +通过[uni.getFileSystemManager](get-file-system-manager.md)可以获取到文件系统管理器，所有文件系统的管理操作通过 [FileSystemManager](get-file-system-manager.md#FileSystemManager) 来调用。 +```uts +const fs = uni.getFileSystemManager() +``` + +文件主要分两大类： +- 代码包文件：指 uni-app x 项目目录中添加的文件，比如static目录下的文件。Android发行后存放在assets目录下。只读。 + + assets + + hybrid + + static + + uni_modules +- 本地磁盘文件：指应用在手机端运行时可访问的磁盘文件。又分以下目录： + + 应用外置沙盒目录（`uni.env.SANDBOX_PATH`）：手机应用的沙盒目录，其中包括缓存文件目录和用户文件目录。在文件管理器中可看到。 + * 缓存文件目录（`uni.env.CACHE_PATH`）：手机运行过程中框架保存缓存文件的目录（cache），系统空间不足时会被自动清理掉 + - uni-download ：下载 + - uni-media ：拍照、相册选择 + - uni-snapshot ：App dom截图 + - uni-crash ：App崩溃日志 + * 用户文件目录（`uni.env.USER_DATA_PATH`）：提供给开发者操作的本地文件目录（files） + + 应用内置沙盒目录（`uni.env.ANDROID_INTERNAL_SANDBOX_PATH`）：存放框架的网络缓存（如网络图片、视频、web-view的缓存）、storage。 + + 沙盒外目录 + +## 代码包文件 + +代码包文件，是源码工程中的静态资源文件，由编译器打包到发行包（如apk）中。全平台都如此。 + +uni-app x的应用在安装后，代码包文件有4个目录： +- assets +- hybrid +- static +- uni_modules + +这些目录的来源和作用，[详见](../compiler/README.md#static) + +assets目录下文件有随机数的存在，很难使用FileSystemManager访问；hybrid下的文件用于web-view组件。\ +所以通过FileSystemManager访问较多的是static目录。 + +FileSystemManager访问代码包文件时，直接写文件路径，如：/static/uni.png、/uni_modules/xxx/static/clear.png。 + +**示例** + +假设static目录下有如下文件："/static/list-mock/mock.json"，要copy到沙盒的files目录（该目录的介绍详见下一章节），可使用如下代码： +```ts +let fileManager = uni.getFileSystemManager() + +fileManager.copyFile({ + srcPath: "/static/list-mock/mock.json", + destPath: `${uni.env.USER_DATA_PATH}/mock.json`, + success: function (res : FileManagerSuccessResult) { + console.log('success', res) + }, + fail: function (res : UniError) { + console.log('fail', res) + }, + complete: function (res : any) { + console.log("complete", res) + } +} as CopyFileOptions) +``` + +> 注意：代码包文件仅可读取和复制，无法动态修改或删除。修改代码包文件一般会copy到沙盒目录后再修改。 + +**真机运行注意** + +App端真机运行期间会做特殊处理，将代码包文件同步到`应用沙盒目录`下的特定目录： +- Android平台 + 保存在应用专属存储空间的外置存储空间根目录下的apps目录，通常为“/sdcard/Android/data/%应用包名%/apps/%应用AppID%/www/” +- iOS平台 + 保存在应用沙盒目录下的Documents/uni-app-x目录，通常为“/%应用沙盒目录%/Documents/uni-app-x/apps/%应用AppID%/www/” + + +## 本地磁盘文件 +本地磁盘文件分沙盒内和沙盒外。 + +沙盒内是指应用安装到设备（通常指手机）后，系统会提供一块独立的文件存储区域。以应用维度隔离，即在同一台设备，不同应用间的本地磁盘文件不能直接相互访问。 + +而沙盒目录，又分内置和外置。外置可以在Android手机自带的系统文件管理器里看到，并且用户可以改动。内置的保护级别更高，无法在系统文件管理器中看到。 + +本地磁盘文件路径格式为： +``` +{{协议名}}://文件路径 +``` +> App端，协议名为"unifile"，不应该直接拼写协议名路径访问本地磁盘文件，推荐使用uni.env中的目录常量获取本地磁盘文件目录的路径。 + +**通过uni.env的目录常量访问本地磁盘文件** + +uni-app x提供了一批uni.env常量，来指定不同的可访问目录。 + +以下示例为在`用户文件目录`下写入hello.txt文件： +```ts +const fs = uni.getFileSystemManager(); +fs.writeFile({ + filePath: `${uni.env.USER_DATA_PATH}/hello.txt`, + data: 'hello uni-app x!', + encoding: 'utf-8' +} as WriteFileOptions); +``` + + +### 外置应用沙盒目录 +目录常量名称：`uni.env.SANDBOX_PATH` + +App端专有目录，为应用沙盒根目录，其下包含了`缓存文件目录`和`用户文件目录`。此目录在不同平台差异较大，不建议直接使用此目录，需开发者根据平台特性谨慎操作。 + +实际保存的目录在不同平台存在差异： +- Android平台 + 应用专属存储空间的外置存储空间根目录，通常为“/Android/data/%应用包名%/”，其下的cache目录为`缓存文件目录`，其下的files目录为`用户文件目录` +- iOS平台 + 应用沙盒虚拟目录，其下包括Document、Library、tmp目录，此目录只可读，不可创建其它目录 + +本目录可以在Android系统的文件管理器中看到。用户在文件管理器中可以查阅删改。手机被root后的沙盒机制也会失效，可以被其他app操作。 + +#### 缓存文件目录cache@cache +目录常量名称：`uni.env.CACHE_PATH` + +缓存文件目录，保存应用运行过程中产生的缓存文件。操作系统或小程序宿主会在存储空间不足时清除缓存文件，因此不要在此目录中保存应用的关键业务数据文件。 + +实际保存的目录在不同平台存在差异： +- Android平台 + 应用专属存储空间的外置存储空间根目录下的cache目录，通常为“/Android/data/%应用包名%/cache/” +- iOS平台 + 应用沙盒目录下的Library/Caches目录 + +uni-app x的部分内置API会产生临时文件会放置在本cache目录，如： +- uni.downloadFile下载的文件 +- uni.chooseImage的拍照或选择的相册文件 + +- dom element的截图API + +推荐：在调用上述API使用完毕临时文件后，就调用 `uni.getFileSystemManager` 的API把临时文件删掉。 + +从HBuilderX 3.99起，重新约定了缓存目录的使用规范。 + +在`uni.env.CACHE_PATH`目录下，uni官方使用了如下目录，请开发者避免使用uni-开头的目录： +- uni-download // uni.downloadFile的默认下载地址 （在HBuilderX 3.98时曾使用目录uniDownloads，从3.99起调整为uni-download） +- uni-media // uni.chooseImage的拍照或选择相册的文件 +- uni-snapshot // element takeSnapShot截图APi存储的路径 +- uni-crash //存放崩溃日志 + * java //java、kotlin层崩溃日志 + * c //c、so库崩溃日志 + +#### 用户文件目录files@files +目录常量名称：`uni.env.USER_DATA_PATH` + +App端和小程序提供了用户文件目录，用于开发者在应用运行期读写文件，此目录不会被操作系统自动清除，由开发者自由管理。 + +实际保存的目录在不同平台存在差异： +- Android平台 + 应用专属存储空间的外置存储空间根目录下的files目录，通常为“/sdcard/Android/data/%应用包名%/files/” +- iOS平台 + 应用沙盒目录下的Document目录 + +### 内置应用沙盒目录 + +目录常量名称：`uni.env.ANDROID_INTERNAL_SANDBOX_PATH` + +该目录无法在手机自带的文件管理器中查看，用户无法修改。除非手机被root。 + +uni-app x框架的一些内置组件和API会涉及缓存文件，存放到本目录，如： +- image/video组件的网络图片缓存 +- web-view组件的缓存 + + +### 沙盒外目录 +FileSystemManager暂不支持访问沙盒外目录。如有相关需求目前需开发uts插件。 \ No newline at end of file diff --git a/docs/api/file-system.md b/docs/api/file-system.md deleted file mode 100644 index 3dca7df2..00000000 --- a/docs/api/file-system.md +++ /dev/null @@ -1,112 +0,0 @@ -# 文件系统 -文件系统提供一套跨平台操作文件的管理接口，包括文件和目录的增删改名、获取信息、读写文件等常用功能。 - -通过[uni.getFileSystemManager](filemanager.md)可以获取到文件系统管理器，所有文件系统的管理操作通过 [FileSystemManager](filemanager.md#FileSystemManager) 来调用。 -```uts -const fs = uni.getFileSystemManager() -``` - -文件主要分两大类： -- 项目包文件：指 uni-app x 项目目录中添加的文件，比如static目录下的文件。Android发行后存放在assets目录下。 -- 本地文件：指 uni-app x 应用在手机端运行时可访问的磁盘文件。又分以下目录： - + 应用沙盒目录：App平台原生应用的沙盒目录，其中包括缓存文件目录和用户文件目录 - * 缓存文件目录：App平台运行过程中框架保存缓存文件的目录 - * 用户文件目录：App平台提供给开发者操作的本地文件目录 - - -## 项目包文件 -项目包文件放置应用首次加载时需要的文件，对于内容较大或需要动态更新的文件，不推荐添加到项目包文件中，可以在应用启动后联网将文件下载到本地。 - -推荐将文件放到static目录（uni_modules下也有static目录），详情参考[工程目录结构](https://uniapp.dcloud.net.cn/tutorial/project.html#static) - -没有在static目录的静态文件(比如image src指定静态路径或import)，发行后会变编译到与static同级的assets目录，其中的文件名会加入随机数以避免重名。 -因为随机数的存在，导致很难使用FileSystemManager访问。所以还是推荐使用static目录。 - -**通过FileSystemManager访问项目包文件** - -通过路径访问项目包文件需从项目根目录开始写文件路径，如：/static/uni.png、/uni_modules/xxx/static/clear.png。 - ->注意：项目包文件仅可读取和复制，无法动态修改或删除。修改项目包文件需要重新发布新版本。 - -**真机运行注意** - -App端真机运行期间会做特殊处理，将项目包文件同步到`应用沙盒目录`下的特定目录： -- Android平台 - 保存在应用专属存储空间的外置存储空间根目录下的apps目录，通常为“/sdcard/Android/data/%应用包名%/apps/%应用AppID%/www/” -- iOS平台 - 保存在应用沙盒目录下的Documents/uni-app-x目录，通常为“/%应用沙盒目录%/Documents/uni-app-x/apps/%应用AppID%/www/” - - -## 本地文件 -本地文件是指应用安装到设备（通常指手机）后，系统会提供一块独立的文件存储区域。在App端将会以应用维度隔离，即在同一台设备，不同应用间的本地文件不能直接相互访问。 - -本地文件路径格式为： -``` -{{协议名}}://文件路径 -``` -> App端，协议名为"unifile"，不应该直接拼写协议名路径访问本地文件，推荐使用uni.env中的目录常量获取本地文件目录的路径。 - -本地文件沙盒目录，分内置和外置。外置可以在Android手机自带的系统文件管理器里看到，并且用户可以改动。内置的保护级别更高，无法在系统文件管理器中看到。 - -**通过uni.env的目录常量访问本地文件** - -以下示例为在`用户文件目录`下写入hello.txt文件： -```ts -const fs = uni.getFileSystemManager(); -fs.writeFile({ - filePath: `${uni.env.USER_DATA_PATH}/hello.txt`, - data: 'hello uni-app x!', - encoding: 'utf-8' -} as WriteFileOptions); -``` - - -### 外置应用沙盒目录 -目录常量名称：`uni.env.SANDBOX_PATH` - -App端专有目录，为应用沙盒根目录，其下包含了`缓存文件目录`和`用户文件目录`。此目录在不同平台差异较大，不建议直接使用此目录，需开发者根据平台特性谨慎操作。 - -实际保存的目录在不同平台存在差异： -- Android平台 - 应用专属存储空间的外置存储空间根目录，通常为“/sdcard/Android/data/%应用包名%/”，其下的cache目录为`缓存文件目录`，其下的files目录为`用户文件目录` -- iOS平台 - 应用沙盒虚拟目录，其下包括Document、Library、tmp目录，此目录只可读，不可创建其它目录 - -本目录可以在Android系统的文件管理器中看到。用户在文件管理器中可以查阅删改。手机被root后的沙盒机制也会失效，可以被其他app操作。 - -#### 缓存文件目录 -目录常量名称：`uni.env.CACHE_PATH` - -App端本地缓存文件目录保存应用运行过程中产生的缓存文件，操作系统会在存储空间不足时清除缓存文件，因此不要在此目录中保存应用的关键业务数据文件。 - -实际保存的目录在不同平台存在差异： -- Android平台 - 应用专属存储空间的外置存储空间根目录下的cache目录，通常为“/sdcard/Android/data/%应用包名%/cache/” -- iOS平台 - 应用沙盒目录下的Library/Caches目录 - -uni-app x的部分内置API会产生临时文件会放置在本cache目录，如： -- uni.downloadFile下载的文件 -- uni.uploadFile上传的文件 -- uni.chooseImage的拍照或选择的相册文件 - -- dom element的截图API - -#### 用户文件目录 -目录常量名称：`uni.env.USER_DATA_PATH ` - -App端用户文件目录提供给开发者在应用运行期保存业务逻辑文件，此目录不会被操作系统自动清除，由开发者完全自由管理。 - -实际保存的目录在不同平台存在差异： -- Android平台 - 应用专属存储空间的外置存储空间根目录下的files目录，通常为“/sdcard/Android/data/%应用包名%/files/” -- iOS平台 - 应用沙盒目录下的Document目录 - -### 内置应用沙盒目录 - -目录常量名称：`uni.env.ANDROID_INTERNAL_SANDBOX_PATH` - -uni-app x框架的一些内置组件和API会涉及缓存文件，存放到本目录，如： -- image/video组件的网络图片缓存 - \ No newline at end of file diff --git a/docs/api/filemanager.md b/docs/api/filemanager.md deleted file mode 100644 index be8ba0c1..00000000 --- a/docs/api/filemanager.md +++ /dev/null @@ -1,21 +0,0 @@ -## uni.getFileSystemManager() @getfilesystemmanager - - - -文件管理器对象，用于操作应用可访问的本地文件空间，在app-Android上是沙盒目录。 - -可实现目录和文件的创建、删除、改名或改路径、遍历目录、获取文件信息、读写文件。 - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/api/get-univerify-manager.md b/docs/api/get-univerify-manager.md index c59bbe56..d2a3cef3 100644 --- a/docs/api/get-univerify-manager.md +++ b/docs/api/get-univerify-manager.md @@ -11,6 +11,8 @@ App一键登陆是替代短信验证码登录的更优选择：对开发者而 2. 客户端API，即本文 3. 服务器API，[详见](https://doc.dcloud.net.cn/uniCloud/uni-login/dev.html) +uni-id-pages，已经内置一键登陆，从云端到客户端均已开发好并开源，推荐使用。[详情](https://doc.dcloud.net.cn/uniCloud/uni-id/app-x.html) + @@ -194,6 +196,7 @@ App一键登陆是替代短信验证码登录的更优选择：对开发者而 ## Tips - 运营商对一键登陆给用户呈现的ui有强制要求：必须有运营商的隐私协议和服务条款、不得默认勾选同意、手机号掩码显示、需要用户手动再点按钮获取而不能自动获取。 - 目前一键登陆的UI可自定义性有限。仅支持配置登录页全屏/半屏、登录页背景色、登录按钮文案以及登录页logo。后续会继续扩展自定义性。 +- 一键登陆并非100%成功，手机没有sim卡和蜂窝网络未开启是最常见的原因，更多错误见上方的错误码列表。在一键登陆无法使用时，可转为短信验证码登录。在uni-id-pages里已经集成了相关逻辑，无需自己开发。[详情](https://doc.dcloud.net.cn/uniCloud/uni-id/app-x.html) diff --git a/docs/collocation/manifest-splashscreen.md b/docs/collocation/manifest-splashscreen.md index e157ca5c..8a94cb49 100644 --- a/docs/collocation/manifest-splashscreen.md +++ b/docs/collocation/manifest-splashscreen.md @@ -1,4 +1,4 @@ -## splash +## splash启动封面图 > HBuilderX 3.99+ @@ -6,6 +6,12 @@ App启动时，系统加载应用渲染首页需要一定的时间，为了避 这个界面，即被称为启动界面，也成称为 splash 或 lauch screen。 +当然并非所有App都需要splash，很多系统应用比如计算器、日历都没有splash。 + +uni-app x中，如不配置splash，则与计算器等应用一致，启动时有轻微闪白，但可以让用户更快的使用首页。 + +如需配置splash，注意避免splash图与首页风格差异太大。因为uni-app x启动速度非常快，splash只是一闪而过，如果颜色差异太大，会让用户视觉不舒服。 + ### Android平台启动界面配置 打开项目的manifest.json文件，在“App启动界面配置”中的“Android启动界面设置”项下配置各设备分辨率启动图： @@ -25,6 +31,8 @@ splash关闭时机可控制，打开项目的manifest.json文件，选择源码 |onShow|首页页面生命周期触发onShow时关闭splash| |onReady|首页页面生命周期触发onReady时关闭splash| +暂不支持其他方式关闭splash。 + 配置示例： ```json diff --git a/docs/compiler/README.md b/docs/compiler/README.md index 3c3ce73e..e7971833 100644 --- a/docs/compiler/README.md +++ b/docs/compiler/README.md @@ -112,3 +112,6 @@ App原生语言的编译过程耗时较长，因此编译器引入了缓存机 └─static uni_modules下的本地静态资源（如图片、字体、音视频等文件）的目录 + +uts、css等代码文件不是静态资源，它们会被编译为新的代码格式（如Android上会被编译为kt）。 +请不要把这些文件放到static目录中，因为会导致代码里已经编进去了，又copy了一份相同文件到发行包中，重复增加了包体积。 \ No newline at end of file -- GitLab