Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
Abbotton
unidocs-zh
提交
7fc97427
U
unidocs-zh
项目概览
Abbotton
/
unidocs-zh
与 Fork 源项目一致
Fork自
DCloud / unidocs-zh
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
U
unidocs-zh
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
7fc97427
编写于
11月 25, 2022
作者:
DCloud_iOS_XHY
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
更新 uts 文档
上级
3daaf388
变更
2
隐藏空白更改
内联
并排
Showing
2 changed file
with
155 addition
and
36 deletion
+155
-36
docs/plugin/uts-for-ios.md
docs/plugin/uts-for-ios.md
+125
-24
docs/plugin/uts-plugin.md
docs/plugin/uts-plugin.md
+30
-12
未找到文件。
docs/plugin/uts-for-ios.md
浏览文件 @
7fc97427
...
...
@@ -83,6 +83,8 @@ class TestClass implements TestProtocol {
### 3.1 配置 Info.plist
当插件需要在原生工程 Info.plist 中添加配置项时,需要在插件的 app-ios 目录中创建 Info.plist 文件
以 hello uts 中的 uts-tencentgeolocation 腾讯定位插件中的配置文件为例:
示例文件在 hello uts 中的位置:
...
...
@@ -110,13 +112,33 @@ Info.plist 示例:
Info.plist 格式及配置规则与 iOS 工程中是一致的,云端打包时会将配置信息合并到原生工程的 Info.plist 中
### 3.2 依赖资源文件
### 3.2 配置 entitlements
> HBuilder X 3.6.11+ 版本支持
当插件需要开启 capabilities 中的相关服务时,需要在插件的 app-ios 目录中创建 UTS.entitlements 文件
比如需要在 capabilities 中勾选 Access WiFi Information 项,对应的 UTS.entitlements 的配置示例:
```
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist
version=
"1.0"
>
<dict>
<key>
com.apple.developer.networking.wifi-info
</key>
<true/>
</dict>
</plist>
```
UTS.entitlements 格式及配置规则与 iOS 工程中是一致的,云端打包时会将配置信息合并到原生工程的 entitlements 配置文件中
### 3.3 依赖资源文件
如果您的插件需要依赖资源文件比如图片,音频等,可将资源文件放到插件目录下
`~/utssdk/app-ios/Resources/`
路径中
云端打包时会将此目录下的所有文件添加到应用 main bundle 中,建议只保存 uts 插件内置的资源文件。
### 3.
3
依赖三方库
### 3.
4
依赖三方库
uts 插件支持依赖三方库,目前仅支持 framework 和 xcframework 静态库
...
...
@@ -126,7 +148,85 @@ uts 插件支持依赖三方库,目前仅支持 framework 和 xcframework 静
以 hello uts 中的 uts-tencentgeolocation 腾讯定位插件为例,本插件需要依赖腾讯定位库
`TencentLBS.framework`
,则将依赖库存放到
`~/uni_modules/uts-tencentgeolocation/utssdk/app-ios/Framework/TencentLBS.framework`
位置即可
## 4 swift 与 UTS 差异重点介绍 (持续更新)
## 4 iOS 平台内置库 DCloudUTSFoundation
> HBuilder X 3.6.11+ 版本支持
DCloudUTSFoundation 为框架内置库,所有 uts 插件都会依赖此基础库
DCloudUTSFoundation 会封装一些常用方法便于开发者直接调用
使用时需要在 uts 文件中先导入 UTSiOS 类,所有方法都通过 UTSiOS 类调用
```
ts
// 从 DCloudUTSFoundation 依赖库中导入 UTSiOS 类
import
{
UTSiOS
}
from
"
DCloudUTSFoundation
"
```
### 4.1 getCurrentViewController(): UIViewController
> HBuilder X 3.6.11+ 版本支持
获取当前 app 显示的 UIViewController 实例
以 hello uts 中的 uts-alert 为例:
示例文件在 hello uts 中的位置:
`~/uni_modules/uts-alert/utssdk/app-ios/index.uts`
```
ts
export
function
showAlert
(
title
:
string
|
null
,
message
:
string
|
null
,
result
:
(
index
:
Number
)
=>
void
)
{
// uts方法默认会在子线程中执行,涉及 UI 操作必须在主线程中运行,通过 DispatchQueue.main.async 方法可将代码在主线程中运行
DispatchQueue
.
main
.
async
(
execute
=
():
void
=>
{
// 初始化 UIAlertController 实例对象 alert
let
alert
=
new
UIAlertController
(
title
=
title
,
message
=
message
,
preferredStyle
=
UIAlertController
.
Style
.
alert
)
// 创建 UIAlertAction 按钮
let
okAction
=
new
UIAlertAction
(
title
=
"
确认
"
,
style
=
UIAlertAction
.
Style
.
default
,
handler
=
(
action
:
UIAlertAction
):
void
=>
{
// 点击按钮的回调方法
result
(
0
)
})
// 创建 UIAlertAction 按钮
let
cancelAction
=
new
UIAlertAction
(
title
=
"
取消
"
,
style
=
UIAlertAction
.
Style
.
cancel
,
handler
=
(
action
:
UIAlertAction
):
void
=>
{
// 点击按钮的回调方法
result
(
1
)
})
// 将 UIAlertAction 添加到 alert 上
alert
.
addAction
(
okAction
)
alert
.
addAction
(
cancelAction
)
// 打开 alert 弹窗
UTSiOS
.
getCurrentViewController
().
present
(
alert
,
animated
=
true
)
})
}
```
#### 4.2 colorWithString(value: string): UIColor
> HBuilder X 3.6.11+ 版本支持
将字符串色值转换为 UIColor
格式支持
-
精简写法的十六进制 如:#f00
-
十六进制 如:#ff0000
-
RGB 如:rgb(255, 0, 0)
-
RGBA 如:rgba(255, 0, 0, 0.5)
-
色值关键字,如: red
示例
```
ts
let
bgColor
=
UTSiOS
.
colorWithString
(
"
#000000
"
)
view
.
backgroundColor
=
bgColor
```
持续更新中
## 5 swift 与 UTS 差异重点介绍 (持续更新)
通过上面的章节的阅读。
...
...
@@ -135,11 +235,11 @@ uts 插件支持依赖三方库,目前仅支持 framework 和 xcframework 静
但是对于一个熟悉 iOS 开发的 swift 语言者来说,有很多常用的习惯发生了改变,我们会在这个章节特别指出,便于开发者加深认识。
###
4
.1 语法差异
###
5
.1 语法差异
-------------------------------
####
4
.1.1 常量和变量
####
5
.1.1 常量和变量
swift 中用
`let`
来声明常量,用
`var`
来声明变量
...
...
@@ -157,7 +257,7 @@ let str = "abc" // 声明一个字符串变量
const
str1
=
"
abc
"
// 声明一个字符串常量
```
####
4
.1.2 可选类型
####
5
.1.2 可选类型
swift 中的可选类型定义为
`类型?`
...
...
@@ -180,7 +280,7 @@ uts 中也支持在变量名称后面加 ?表示可选类型,这是标准 ts
let
user
?:
string
=
null
```
####
4
.1.3 调用构造方法
####
5
.1.3 调用构造方法
swift 中调用构造方法创建实例对象时不需要使用
`new`
关键字
...
...
@@ -195,7 +295,7 @@ var alert = new UIAlertController()
```
####
4
.1.4 函数参数标签
####
5
.1.4 函数参数标签
在 swift 中方法参数存在标签时使用
`:`
连接在标签和参数值之间,在 uts 中需要使用
`=`
连接
...
...
@@ -212,7 +312,7 @@ var alert = UIAlertController(title: "提示", message: "提示内容", preferre
let
alert
=
new
UIAlertController
(
title
=
"
提示
"
,
message
=
"
提示内容
"
,
preferredStyle
=
UIAlertController
.
Style
.
alert
)
```
####
4
.1.5 枚举值
####
5
.1.5 枚举值
枚举在 swift 中可以忽略枚举类型直接简写
`.枚举值`
,在 uts 中不支持简写,需要完整的写出
`枚举类型.枚举值`
上面的示例中 swift 中最后一个参数 preferredStyle 的值可以简写为
...
...
@@ -228,7 +328,7 @@ UIAlertController.Style.alert
```
####
4
.1.6 类继承
####
5
.1.6 类继承
swift 中定义子类继承父类时需要在子类名称后加上父类名称,中间以冒号
`:`
分隔
...
...
@@ -248,7 +348,7 @@ class Son extends Father {
}
```
####
4
.1.7 遵循协议方法
####
5
.1.7 遵循协议方法
swift 中要让自定义类型遵循某个协议,在定义类型时,需要在类型名称后加上协议名称,中间以冒号
`:`
分隔。遵循多个协议时,各协议之间用逗号
`,`
分隔:
...
...
@@ -266,7 +366,7 @@ class SomeClass implements FirstProtocol, AnotherProtocol {
}
```
####
4
.1.8 系统版本判断
####
5
.1.8 系统版本判断
swift 中系统版本判断的方法
...
...
@@ -285,7 +385,7 @@ if (UIDevice.current.systemVersion >= "10.0") {
}
```
####
4
.1.9 闭包
####
5
.1.9 闭包
swift 中闭包可以简写
...
...
@@ -305,7 +405,7 @@ let action = new UIAlertAction(title="确认", style=UIAlertAction.Style.default
})
```
####
4
.1.10 target-action 方法
####
5
.1.10 target-action 方法
uts 中调用原生中涉及 target-action 的方法时,比如给
`UIButton`
添加点击事件方法、注册通知中心事件方法时注意事项,
...
...
@@ -333,7 +433,7 @@ NotificationCenter.default.addObserver(this, selector = method, name = UIApplica
}
```
####
4
.1.11 字典类型
####
5
.1.11 字典类型
swift 中的 Dictionary 类型,在 uts 中使用 Map 类型代替
...
...
@@ -348,7 +448,8 @@ value["name"] = "uts"
let
map
:
Map
<
string
,
any
>
=
new
Map
()
map
.
set
(
"
name
"
,
"
uts
"
)
```
#### 4.1.12 覆写方法存在参数标签的兼容问题
#### 5.1.12 覆写方法存在参数标签的兼容问题
> HBuilder X 3.6.11+ 版本支持
当覆写系统方法,或实现三方SDK的协议方法时,一些方法可能会存在参数标签的情况
...
...
@@ -392,9 +493,9 @@ tencentLBSLocationManager(manager: TencentLBSLocationManager, @argumentLabel("di
##
5
常见问题(持续更新)
##
6
常见问题(持续更新)
###
5
.1 如何在UTS环境中,获取当前 UIViewController 实例
###
6
.1 如何在UTS环境中,获取当前 UIViewController 实例
参考 Hello UTS 项目中的 uts-alert 插件
...
...
@@ -402,7 +503,7 @@ tencentLBSLocationManager(manager: TencentLBSLocationManager, @argumentLabel("di
> ~/uni_modules/uts-alert/utssdk/app-ios/index.uts
###
5
.2 如何在UTS环境中,操作 UI 线程
###
6
.2 如何在UTS环境中,操作 UI 线程
```
DispatchQueue.main.async(execute=():void => {
...
...
@@ -417,9 +518,9 @@ DispatchQueue.main.async(execute=():void => {
##
6
已知待解决问题(持续更新)
##
7
已知待解决问题(持续更新)
###
6
.1 语法提示问题
###
7
.1 语法提示问题
HBuilderX 目前写iOS uts 插件时部分语法提示会有缺失、参数类型不准确的问题,例如:
...
...
@@ -430,13 +531,13 @@ HBuilderX 目前写iOS uts 插件时部分语法提示会有缺失、参数类
这些问题会在后续版本中优化
###
6
.2 语法不兼容问题
###
7
.2 语法不兼容问题
####
6
.2.1 for 循环语法问题
####
7
.2.1 for 循环语法问题
-
for in 循环目前有语法兼容问题
-
for (int i = 0, i < array.length, i++) 方法目前有语法兼容问题
###
6
.3 类型兼容问题
###
7
.3 类型兼容问题
-
元祖类型目前不支持
docs/plugin/uts-plugin.md
浏览文件 @
7fc97427
...
...
@@ -129,6 +129,7 @@ package.json 为 uni_modules 插件配置清单文件,负责描述插件的基
│ │ ├─Frameworks //iOS原生依赖的第三方 framework 依赖库存放目录,可选
│ │ ├─Resources //iOS原生所依赖的资源文件存放目录,可选
│ │ ├─info.plist //iOS原生所需要添加到主 info.plist 文件中的配置文件,可选
│ │ ├─UTS.entitlements //iOS原生所需要添加到主工程 .entitlements 文件中的配置文件,可选
│ │ ├─config.json //iOS原生配置文件
│ │ └─index.uts //iOS原生插件能力实现
│ ├─web //web平台目录
...
...
@@ -282,13 +283,14 @@ dependencies {
app-ios 文件夹下存在iOS平台原生配置,包括以下目录或文件
|目录名/文件名 |用途 |
|:--- |:--- |
|Frameworks |iOS平台插件需要引用的三方 framework 依赖库存放目录 |
|Resources |iOS平台插件需要引用的资源文件存放目录 |
|Info.plist |iOS平台插件需要添加到原生工程Info.plist中的配置文件 |
|config.json |iOS平台原生工程的配置文件 |
|index.uts |主入口,index.d.ts声明的能力在iOS平台下的实现 |
|目录名/文件名 |用途 |
|:--- |:--- |
|Frameworks |iOS平台插件需要引用的三方 framework 依赖库存放目录 |
|Resources |iOS平台插件需要引用的资源文件存放目录 |
|Info.plist |iOS平台插件需要添加到原生工程Info.plist中的配置文件 |
|UTS.entitlements |iOS平台插件需要添加到原生工程 entitlements 文件中的配置文件 |
|config.json |iOS平台原生工程的配置文件 |
|index.uts |主入口,index.d.ts声明的能力在iOS平台下的实现 |
##### Frameworks
iOS平台插件依赖的三方库存放目录,支持以下类型文件:
...
...
@@ -308,17 +310,15 @@ iOS平台原生 Info.plist 文件配置,云端打包时会将配置信息合
除了插件下有Info.plist,项目下也有。注意2者的区别。一般使用者的配置不放在插件下,而放在自己的项目下。项目下配置
[
详见
](
https://uniapp.dcloud.net.cn/tutorial/app-nativeresource-ios.html#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6-info-plist
)
示例: 添加
位置权限描述信息
和 开启后台定位
示例: 添加
自定义字段 TencentLBSAPIKey
和 开启后台定位
```
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist
version=
"1.0"
>
<dict>
<key>
NSLocationAlwaysUsageDescription
</key>
<string>
访问位置权限
</string>
<key>
NSLocationWhenInUseUsageDescription
</key>
<string>
使用期间获取位置权限
</string>
<key>
TencentLBSAPIKey
</key>
<string>
填写您申请的APIKey
</string>
<key>
UIBackgroundModes
</key>
<array>
<string>
location
</string>
...
...
@@ -327,6 +327,24 @@ iOS平台原生 Info.plist 文件配置,云端打包时会将配置信息合
</plist>
```
##### UTS.entitlements
iOS平台原生 entitlements 文件配置,云端打包时会将配置信息合并到原生工程的 entitlements 配置文件中
插件需要开启 capabilities 中的相关服务时需要配置 UTS.entitlements 文件
示例:在 capabilities 中勾选 Access WiFi Information 项后对应的 UTS.entitlements 的配置
```
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist
version=
"1.0"
>
<dict>
<key>
com.apple.developer.networking.wifi-info
</key>
<true/>
</dict>
</plist>
```
##### config.json
uts插件在iOS平台的其它原生配置文件,可以在其中配置依赖的系统库等信息
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录