From cc9782aa06ee4ceac5fcc229546d9546ca0f41aa Mon Sep 17 00:00:00 2001 From: wanganxp Date: Thu, 27 Jun 2024 01:45:47 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/_sidebar.md | 8 +- docs/i18n.md | 315 ++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 21 ++- docs/worktile/README.md | 4 +- 4 files changed, 332 insertions(+), 16 deletions(-) create mode 100644 docs/i18n.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 44c0a8c0..b73f6378 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -30,11 +30,13 @@ * 运行和调试 * [真机运行](https://uniapp.dcloud.net.cn/tutorial/run/run-app.html) * [Android审查元素](debug/android-inspector.md) - * [uts插件Android Debug](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug.html) - * [uts插件iOS Debug](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug-ios.html) + * [uts插件Android Debug](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug.html) + * [uts插件iOS Debug](https://uniapp.dcloud.net.cn/tutorial/debug/uni-uts-debug-ios.html) * [性能优化](performance.md) -* [源码和示例](sample.md) * [uni错误规范](https://uniapp.dcloud.net.cn/tutorial/err-spec.html) +* [暗黑模式](api/theme.md) +* [国际化](i18n.md) +* [源码和示例](sample.md) * [跨平台框架及原生对比](select.md) * 更新日志 * [正式版](release.md) diff --git a/docs/i18n.md b/docs/i18n.md new file mode 100644 index 00000000..c40c4869 --- /dev/null +++ b/docs/i18n.md @@ -0,0 +1,315 @@ +uni-app x的国际化，即多语言，分2种情况： +1. 固定一种外语：这种方式很简单，自己直接写就可以 +2. 动态切换语言：内置多种语言，根据条件动态切换。这种略微复杂，需要仔细读下文。 + +首先需要分清楚，一个应用分为开发者的代码，和uni-app x框架代码2部分。它们都涉及国际化。 + +- 开发者代码：即开发者自己的代码里涉及的界面部分 +- 框架部分：即uni-app x内置组件和API涉及界面的部分 + + +## 开发者代码的国际化 + +这里的国际化指动态切换语言。如果是写死一种语言，直接在代码里写就好了。 + +### App平台 + +i18n这个vue插件库还没有适配uts，但自己实现一个语言替换机制也不难。 + +推荐使用这个插件来解决动态语言切换，[lime-i18n](https://ext.dcloud.net.cn/plugin?id=18954) + +### Web平台 + +Web平台可以使用标准的vue-i18n插件。 + +main.uts 引入并初始化 VueI18n。（注意写条件编译，避免App平台报错） + +```js +// 国际化 json 文件，文件内容详见下面的示例 +import en from './en.json' +import zhHans from './zh-Hans.json' +import zhHant from './zh-Hant.json' +const messages = { + en, + 'zh-Hans': zhHans, + 'zh-Hant': zhHant +} + +let i18nConfig = { + locale: uni.getLocale(),// 获取已设置的语言 + messages +} + +import { createSSRApp } from 'vue' +import { createI18n } from 'vue-i18n'// v9.x +const i18n = createI18n(i18nConfig) +export function createApp() { + const app = createSSRApp(App) + app.use(i18n) + return { + app + } +} +``` + +国际化json文件内容 + +```json +{ + "index.title": "Hello i18n" +} +``` + +页面模板中使用 `$t()` 获取，并传递国际化json文件中定义的key，js中使用 `this.$t('')` + +```html + + + +``` + +注意：页面中设置语言后需要调用 `this.$i18n.locale = 'zh-Hans'` 后生效 + + +## pages.json 国际化@pages + +Web平台和App平台，可以通过设置tabbar和navigationbar的API来设置文字。 + +Web平台还额外支持如下使用方式： + +项目根目录的locale目录下配置语言json文件，locale/`语言地区代码`.json，如：en.json，zh-Hans.json，zh-Hant.json + +``` +├── locale +│ ├── en.json +│ ├── zh-Hans.json +│ └── zh-Hant.json +``` + +语言文件示例（zh-Hans.json） + +```json +{ + "app.name": "Hello uni-app", + "index.title": "首页" +} +``` + +pages.json 示例 + +```json +{ + "pages": [ + { + "path": "pages/index/index", + "style": { + "navigationBarTitleText": "%index.title%" // locale目录下 语言地区代码.json 文件中定义的 key，使用 %% 占位 + } + } + ], + "tabBar": { + "list": [{ + "pagePath": "pages/index/index", + "text": "%index.home%" + } + ] + } +} +``` + +pages.json 支持以下属性配置国际化信息 + +- navigationBarTitleText +- titleNView->titleText +- titleNView->searchInput->placeholder +- tabBar->list->text + + +## 框架内置组件和API国际化 + +uni-app x 的部分组件和API涉及界面，框架内置如下5种语言，如果手机os或浏览器语言在这5种内，会自适应。如果不在5种内，会默认为英文。 +* 中文简体 +* 中文繁体 +* 英语 +* 法语 +* 西班牙语 + +涉及界面的组件和API包括： +- showModal：默认的确定和取消按钮文字。会根据os和浏览器的语言自适应。也可以在API中通过参数自己指定文字。 +- showActionSheet：取消按钮文字。会根据os和浏览器的语言自适应。 +- chooseImage和chooseVideo： + * 打开的相机时是系统相机，跟随系统语言，不受uni-app x内置的5种语言限制。 + * 打开相册时，web平台是浏览器界面，不受uni-app x内置5种语言限制；app平台内置中英文，在这2种中自适应。 + + +### 自定义国际化内容@uni-framework + +> 仅web平台支持 + +如果自动适配语言不满足你的需求，比如需要预置的5种语言外的更多语言。那么可以使用自定义方案。在指定目录创建指定文件，用同名词条来替换，语言地区代码请遵循 BCP47 规范。 + +项目根目录支持 `locale` 目录，locale/uni-app.`语言地区代码`.json，如：uni-app.en.json，uni-app.zh-Hans.json，uni-app.zh-Hant.json + + +``` +├── locale +│ ├── uni-app.en.json +│ ├── uni-app.zh-Hans.json +│ └── uni-app.zh-Hant.json +``` + +uni-app.zh-Hans.json 文件 + +```json +{ + "common": { + "uni.async.error": "连接服务器超时，点击屏幕重试", + "uni.showActionSheet.cancel": "取消", + "uni.showModal.cancel": "取消", + "uni.showModal.confirm": "确定", + "uni.chooseImage.cancel": "取消", + "uni.chooseImage.sourceType.album": "从相册选择", + "uni.chooseImage.sourceType.camera": "拍摄", + "uni.chooseVideo.cancel": "取消", + "uni.chooseVideo.sourceType.album": "从相册选择", + "uni.chooseVideo.sourceType.camera": "拍摄", + "uni.setClipboardData.success": "内容已复制", + }, + "ios": {}, + "android": {} +} +``` + + + +## manifest.json 国际化@manifest + +云打包暂不支持动态调整应用名称的语言。目前只能写死一种语言。 + +离线打包可自行在离线打包工程中配置。 + +## info.plist国际化 + +info.plist中涉及隐私弹框时的提示文字。 + +云打包文档待补充。 + +离线打包可自行在离线打包工程中配置。 + +## uniCloud国际化 + +注：大陆以外的终端用户访问uniCloud，开通阿里云的海外加速后可以提高访问速度。[详见](https://doc.dcloud.net.cn/uniCloud/faq.html#global-accelerate) + +### DB Schema 国际化@schema + +uniCloud的 DB Schema 中涉及字段的显示名称、错误格式提示语，这些也需要国际化。 + +在项目根目录 uniCloud/database/locale/{数据库表名}/`语言地区代码`.json 文件，然后在 `*.schema.json` 文件中使用 %% 占位 + +``` +├─uniCloud +│ ├─cloudfunctions +│ └─database +│ │ hello.schema.json +│ └─locale +│ └─hello +│ en.json +│ zh-Hans.json +``` + +hello.schema.json 文件内容 + +```json +// 文档教程: https://doc.dcloud.net.cn/uniCloud/schema +{ + "bsonType": "object", + "required": [], + "permission": { + "read": false, + "create": false, + "update": false, + "delete": false + }, + "properties": { + "_id": { + "description": "ID" + }, + "name": { + "bsonType": "string", + "label": "%name%", + "errorMessage": { + "format": "{label}%name.format%" + } + } + } +} +``` + +en.json 文件内容 + +```json +{ + "name": "Name", + "name.format": " invalid format" +} +``` + +zh-Hans 文件内容 + +```json +{ + "name": "姓名", + "name.format": "格式无效" +} +``` + + +## App第三方SDK界面的国际化 + +Web平台 内置支持Google地图。 + +其他如海外的支付、登录等app sdk，需自行开发插件或去插件市场搜索。 + + +## 语言API + +uni-app内置获取os或浏览器语言的API。 + +- [uni.getSystemInfo](./api/get-system-info.md) +- [uni.getDeviceInfo](./api/get-device-info.md) + +Web平台还支持以下更多功能。 + +Web平台注意要区分系统语言和应用语言的概念。 + +可以得到设备OS的语言、运行宿主host的语言以及应用自身的语言。 + +- [uni.getLocale](/api/ui/locale?id=getlocale) + +获取应用当前使用的语言 + +- [uni.setLocale](/api/ui/locale?id=setlocale) + +设置应用语言 + +- [uni.onLocaleChange](/api/ui/locale?id=onlocalechange) + +当前应用语言发生变化时，触发回调。也就是`uni.setLocale`执行时。 + + +## 语言代码 + +语言代码通常为两个或三个字母，参考[ISO 639](https://zh.wikipedia.org/wiki/ISO_639-1%E4%BB%A3%E7%A0%81%E8%A1%A8)规范 + +语言代码-地区代码，地区代码为两个字母，参考[ISO 3166-2](https://zh.wikipedia.org/wiki/ISO_3166-2)规范 \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md index 7a649307..76c7b58c 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -109,7 +109,7 @@ uvue渲染引擎包括uts版的vue框架（组件、数据绑定...）、跨平 ``` -uvue支持的是vue3语法，支持组合式API。详见[vue语法](./vue/README.md) +uvue支持的是vue3语法，支持组合式API和选项式API。详见[vue语法](./vue/README.md) uvue在App端支持的css语法，是web的子集，类似于但优于nvue的css。仅支持flex布局，但也足以布局出需要的界面。详见[css语法](./css/README.md) @@ -275,9 +275,8 @@ uni-app x支持npm，但npm的大多数库是for web的，无法跨端，这些 除上述文档中声明已经完成的，还有如下需要注意： - 平台支持：Android、Web、iOS版已发布。小程序、鸿蒙还未支持。虽然uts语言支持swift，可以写原生插件，但uvue的iOS版目前只上线了js逻辑层，还未发布swift逻辑层。 -- 小程序平台：目前也可以通过编译到H5，在小程序的web-view里临时替代使用 -- 鸿蒙next平台：DCloud内部已经立项。推荐不熟悉ts的开发者先学习ts，鸿蒙的artTs和uts，都是ts的变种，掌握类型系统是必须的。 -- 目前不支持：暗黑模式（一些三方组件库自行实现了主题切换）、自定义路由、多语言、无障碍 +- 小程序平台：目前也可以通过编译到H5，在小程序的web-view里临时替代使用。24年下半年会正式支持小程序。 +- 鸿蒙next平台：24年7月会发布uni-app编译为鸿蒙hap，采用web-view；下半年内会提供uni-app x编译为鸿蒙hap，采用原生渲染。推荐不熟悉ts的开发者先学习ts，鸿蒙的artTs和uts，都是ts的变种，掌握类型系统是必须的。 - 目前不支持国际区账户创建和打包uni-app x，仅大陆区开发者账户可用。 ::: info @@ -321,19 +320,16 @@ uni-app x 毕竟是原生应用，内嵌flutter、rn这些没有任何问题， ## FAQ - uni-app x 支持uvue页面和vue页面混写吗？\ - 仅支持uvue页面。Android平台没有内置js引擎，不能运行vue页面。但历史vue页面可以通过 uni小程序sdk 嵌入到uni-app x中。 + 仅支持uvue页面。Android平台没有内置js引擎，不能运行vue页面。但历史vue页面可以通过 [uni小程序sdk](https://ext.dcloud.net.cn/plugin?id=17638) 嵌入到uni-app x中。 - uni-app x 的app端能离线打包吗？\ - 初期不能，后期会提供 + 可以。[详见](./native/README.md) - uni-app x 的App能热更新吗？\ 开发期间可以热刷，但打包后不能热更新。\ - Android作为原生应用，可以使用uni小程序sdk，热更新小程序。当然开发者也可自行封装原生的插件动态加载方案。\ + Android作为原生应用，可以使用[uni小程序sdk](https://ext.dcloud.net.cn/plugin?id=17638)，热更新小程序。当然开发者也可自行封装原生的插件动态加载方案。\ iOS平台的js逻辑层模式，未来会推出wgt更新。 -- uni-app x 会搞插件大赛吗？\ - 已经启动。欢迎大家做基于uts和uvue的插件。[详情](https://ask.dcloud.net.cn/article/40812) - - uni-app x 能调用所有原生API吗？\ 可以。在app端，kotlin和swift能调用的，uts就能调。在浏览器端，所有js能调用的，uts也都能调。 @@ -341,7 +337,8 @@ uni-app x 毕竟是原生应用，内嵌flutter、rn这些没有任何问题， 可以，通过uts插件，[https://uniapp.dcloud.net.cn/plugin/uts-plugin.html](https://uniapp.dcloud.net.cn/plugin/uts-plugin.html) - uvue页面里的script可以直接调用原生代码吗？还是必须封装成uni_modules方式的uts原生插件？\ - uvue的script里写的就是uts，Android端可以直接调原生代码。无所谓它在`uni_modules`里还是外。但如果是大段的原生代码调用，还是推荐封装为独立的`uni_modules`。iOS平台如果是js逻辑层模式，只能在独立`uni_modules`中才能调用原生。 + uvue的script里写的就是uts，Android端可以直接调原生代码。无所谓它在`uni_modules`里还是外。但如果是大段的原生代码调用，还是推荐封装为独立的`uni_modules`。\ + iOS平台如果是js逻辑层模式，只能在独立`uni_modules`中才能调用原生。 - uni-app x 的开发只能用HBuilderX吗？\ 是的。为三方ide做插件是一个投资大且充满不确定性的事情，官方有限精力会聚焦在自身产品优化上。但DCloud是开放的，不会限制三方ide的插件支持。欢迎社区投入支持。 @@ -354,7 +351,7 @@ uni-app x 毕竟是原生应用，内嵌flutter、rn这些没有任何问题， - uni-app x开源吗？ * Web版开源地址：[https://github.com/dcloudio/uni-app](https://github.com/dcloudio/uni-app) - * App版的组件和API实现大都开源，会陆续发布在项目[uni-api](https://gitcode.net/dcloud/uni-api)和[uni-component](https://gitcode.net/dcloud/uni-component)下。\ + * App版的组件和API实现大都开源，持续更新在项目[uni-api](https://gitcode.net/dcloud/uni-api)和[uni-component](https://gitcode.net/dcloud/uni-component)下。\ 开发者可以了解组件和API的实现，直接修改或优化源码，修改后的代码以[ext api](https://uniapp.dcloud.net.cn/api/extapi.html)或组件的方式下载到项目中，即可实现在本项目中替换掉官方组件和API。 - 未来 uni-app js引擎版还维护吗？\ diff --git a/docs/worktile/README.md b/docs/worktile/README.md index 4e09990d..193941c5 100644 --- a/docs/worktile/README.md +++ b/docs/worktile/README.md @@ -3,5 +3,7 @@ uni-app x 支持的工程化支持，主要包括： - 版本管理控制：如git/svn -- 运行环境管理 +- 运行环境管理：如`if (process.env.NODE_ENV === 'development') `，[详见](https://uniapp.dcloud.net.cn/worktile/running-env.html) - 自动化测试 + +uni-app x不支持cli创建项目，但HBuilderX创建的项目，可以调用HBuilderX的cli来通过命令行打包。[详见](https://hx.dcloud.net.cn/cli/README) \ No newline at end of file -- GitLab