Merge branch 'master' into patch-1

Strezless1 · Oct 30, 2020 · a1017a2 · a1017a2
2 parents 20864d4 + 4d8b0a2
commit a1017a2
Show file tree

Hide file tree

Showing 72 changed files with 3,813 additions and 57 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -16,7 +16,7 @@ JSBox 从 2.0 开始，提供了对 Node.js 运行时的支持。关于这一部
 
 - 通过 URL Scheme 在线安装
 
-  > 例如通过在 iOS 设备上点击：jsbox://import?url=https%3A%2F%2Fraw.githubusercontent.com%2Fcyanzhong%2FxTeko%2Fmaster%2Fextension-scripts%2Fapi.js&name=%E6%B5%8B%E8%AF%95%E5%9C%A8%E7%BA%BF%E5%AE%89%E8%A3%85&icon=icon_063.png
+  > 例如通过在 iOS 设备上点击：jsbox://import?url=url&name=name&icon=icon
   > 将会打开 JSBox 自动安装脚本，支持 `url`, `name`(可选), `icon`(可选) 3 个参数，均需要 URL Encode
   > icon 名称具体请参考：https://github.com/cyanzhong/xTeko/tree/master/extension-icons
   > 在线文件 URL 中请使用纯英文名

diff --git a/docs/_navbar.md b/docs/_navbar.md
@@ -1,3 +1 @@
-- Translations
-  - [:cn: 中文](/)
-  - [:us: English](/en/)
+- [EN / **CN**](/en/)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -36,6 +36,7 @@
   - [动画](uikit/animation.md)
   - [长按菜单](uikit/context-menu.md)
   - [接口](uikit/method.md)
+  - [Dark Mode](uikit/dark-mode.md)
 
 - 控件列表
   - [标签](component/label.md)
@@ -68,7 +69,15 @@
   - [代码视图](component/code.md)
   - [Runtime](component/runtime.md)
 
-- Today 小组件
+- 桌面小组件（iOS 14）
+  - [前言](home-widget/intro.md)
+  - [时间线](home-widget/timeline.md)
+  - [视图](home-widget/views.md)
+  - [布局](home-widget/layout.md)
+  - [属性](home-widget/modifiers.md)
+  - [方法](home-widget/method.md)
+
+- Today 小组件（已过时）
   - [前言](widget/intro.md)
   - [方法](widget/method.md)
 

diff --git a/docs/about/changelog.md b/docs/about/changelog.md
@@ -1,3 +1,11 @@
+# 2020.10.03
+
+- 增加桌面小组件相关：[详情](home-widget/intro.md)
+
+# 2020.03.13
+
+- 增加 Dark Mode 相关：[详情](uikit/dark-mode.md)
+
 # 2020.03.04
 
 - 增加富文本相关：[详情](component/text.md)

diff --git a/docs/addin/method.md b/docs/addin/method.md
@@ -13,6 +13,7 @@ var addins = $addin.list
 属性 | 类型 | 读写 | 说明
 ---|---|---|---
 name | string | 读写 | 名称
+category | string | 读写 | 分类
 url | string | 读写 | url
 data | $data | 读写 | 文件
 id | string | 读写 | id
@@ -25,6 +26,26 @@ website | string | 读写 | 网站
 
 以上字段 `name` 和 `data` 为必须，其余字段可选。
 
+你可以对取出的 `addins` 进行更改，例如重新排序，然后这样保存：
+
+```js
+$addin.list = addins;
+```
+
+# $addin.categories
+
+获取当前设备所有的脚本分类，返回 string 数组：
+
+```js
+const categories = $addin.categories;
+```
+
+你可以进行修改，例如重新排序或增加分类，然后这样保存：
+
+```js
+$addin.categories = categories;
+```
+
 # $addin.current
 
 获取当前正在运行的脚本，结构如上述所示：

diff --git a/docs/component/blur.md b/docs/component/blur.md
@@ -6,16 +6,16 @@
 {
   type: "blur",
   props: {
-    style: 1 // 0 ~ 5
+    style: 1 // 0 ~ 20
   },
   layout: $layout.fill
 }
 ```
 
-`style` 0 ~ 5 表示了不同的模糊效果。
+`style` 0 ~ 20 表示了不同的模糊效果，[参考](data/constant.md?id=blurstyle)。
 
 # props
 
 属性 | 类型 | 读写 | 说明
 ---|---|---|---
-style | number | w | 效果类型
+style | $blurStyle | w | 效果类型
diff --git a/docs/component/canvas.md b/docs/component/canvas.md
@@ -148,6 +148,20 @@
 
 对闭合的路径进行描边。
 
+# drawPath(mode)
+
+使用指定模式绘制路径：
+
+```
+0: kCGPathFill,
+1: kCGPathEOFill,
+2: kCGPathStroke,
+3: kCGPathFillStroke,
+4: kCGPathEOFillStroke,
+```
+
+参考：https://developer.apple.com/documentation/coregraphics/1455195-cgcontextdrawpath
+
 # drawImage(rect, image)
 
 将 `image` 绘制到 `rect` 这个矩形上。

diff --git a/docs/component/gallery.md b/docs/component/gallery.md
@@ -46,6 +46,7 @@
 items | object | 只写 | 每个分页项
 page | number | 读写 | 当前页数
 interval | number | 读写 | 自动播放间隔，为 0 表示不播放
+pageControl | $view | 只读 | 页面控制组件
 
 # events
 
@@ -64,4 +65,12 @@ changed: function(sender) {
 ```js
 const views = $("gallery").itemViews; // All views
 const view = $("gallery").viewWithIndex(0); // The first view
+```
+
+# 滚动到某一页
+
+设置 `page` 将直接切换到某一页，如果需要带着动画滚动过去，请使用：
+
+```js
+$("gallery").scrollToPage(index);
 ```
diff --git a/docs/component/map.md b/docs/component/map.md
@@ -1,6 +1,6 @@
 # type: "map"
 
-`map` 用于创建一个地图，目前只是简单的支持在地图上显示位置：
+`map` 用于创建一个地图，目前只是简单地支持在地图上显示位置：
 
 ```js
 {

diff --git a/docs/component/markdown.md b/docs/component/markdown.md
@@ -8,7 +8,13 @@ $ui.render({
     {
       type: "markdown",
       props: {
-        content: "# Hello, *World!*"
+        content: "# Hello, *World!*",
+        style: // optional, custom style sheet
+        `
+        body {
+          background: #f0f0f0;
+        }
+        `
       },
       layout: $layout.fill
     }
@@ -20,4 +26,5 @@ $ui.render({
 ---|---|---|---
 webView | $view | r | webView
 content | string | rw | 内容
-scrollEnabled | bool | rw | 是否滚动
+scrollEnabled | bool | rw | 是否滚动
+style | string | rw | 自定义样式
diff --git a/docs/component/matrix.md b/docs/component/matrix.md
@@ -55,6 +55,8 @@ direction | $scrollDirection | 只写 | .vertical: 纵向 .horizontal: 横向
 selectable | boolean | 读写 | 是否可被选中
 waterfall | boolean | 只写 | 是否瀑布流布局
 
+请使用有限的、确定的约束条件来实现方块大小，使用 `waterfall` 时必须指定 `columns`，布局冲突将会引起应用崩溃。
+
 # header & footer
 
 `header` 和 `footer` 是放在头部和尾部的自定义 view，是可选项（在 props 里）：
@@ -72,7 +74,23 @@ footer: {
 }
 ```
 
-请在 props 里面指定他的高度 `height`。
+如果高度是固定的，请在 `props` 里面指定他的高度 `height`。如需动态改变高度，可在 `events` 里指定一个 `height` 函数：
+
+```js
+footer: {
+  type: "label",
+  props: {
+    text: "Write the Code. Change the world."
+  },
+  events: {
+    height: sender => {
+      return _height;
+    }
+  }
+}
+```
+
+需要改变高度时，修改上述 `_height` 值，然后调用 `matrix.reload()` 进行更新。若创建的视图为横向滚动，则使用 `width` 代替上述 `height` 来指定宽度。
 
 # object($indexPath)
 

diff --git a/docs/component/picker.md b/docs/component/picker.md
@@ -79,4 +79,16 @@ changed: function(sender) {
 
 # $picker.data(object)
 
-创建一个通用选择器的快捷方式，参数和上面的方式相同，picker 将会直接从屏幕底部弹出。
+创建一个通用选择器的快捷方式，参数和上面的方式相同，picker 将会直接从屏幕底部弹出。
+
+以上两个方法的参数和之前提到的格式完全相同。
+
+# $picker.color(object)
+
+使用内建的颜色选择器来选择颜色：
+
+```js
+const color = await $picker.color({
+  // color: aColor
+});
+```
diff --git a/docs/component/scroll.md b/docs/component/scroll.md
@@ -135,11 +135,19 @@ willBeginDragging: function(sender) {
 `willEndDragging` 在将要结束拖拽时回调：
 
 ```js
-willEndDragging: function(sender, velocity) {
+willEndDragging: function(sender, velocity, target) {
 
 }
 ```
 
+其中 `target` 为滚动停下来时候的位置，可以通过返回一个 `$point` 进行覆盖：
+
+```js
+willEndDragging: function(sender, velocity, target) {
+  return $point(0, 0);
+}
+```
+
 # events: didEndDragging
 
 `didEndDragging` 在已经结束拖拽时回调：

diff --git a/docs/component/text.md b/docs/component/text.md
@@ -126,6 +126,8 @@ $ui.render({
 });
 ```
 
+若需表示 `*`, `_` 等特殊符号，请使用 `\\` 进行转义。
+
 如果需要对格式进行更精细的控制，可以通过 `styles` 为文字的不同位置指定样式：
 
 ```js
@@ -160,6 +162,7 @@ $ui.render({
           text: text,
           font: $font(17),
           color: $color("black"),
+          markdown: false, // whether to use markdown syntax
           styles: [
             {
               range: _range("AmericanTypewriter"),
@@ -225,16 +228,39 @@ font | $font | 字体
 color | $color | 前景色
 bgcolor | $color | 背景色
 kern | number | 字距
-strikethroughStyle | number | 删除线样式（0: 无 1: 细线 2: 细线 9: 双线）
+strikethroughStyle | number | 删除线样式 [Refer](https://developer.apple.com/documentation/uikit/nsunderlinestyle?language=objc)
 strikethroughColor | $color | 删除线颜色
-underlineStyle | number | 下划线样式（0: 无 1: 细线 2: 细线 9: 双线）
+underlineStyle | number | 下划线样式 [Refer](https://developer.apple.com/documentation/uikit/nsunderlinestyle?language=objc)
 underlineColor | $color | 下划线颜色
 strokeWidth | number | 描边宽度
 strokeColor | $color | 描边颜色
 link | string | 链接 URL
 baselineOffset | number | 基线偏移
 obliqueness | number | 字体倾斜
 
+使用 `styles` 默认不使用 markdown 语法，也可以通过 `markdown: true` 开启。
+
+关于下划线和删除线，请参考 Apple 提供的文档，在此做一个简单的举例：
+
+```js
+NSUnderlineStyleNone = 0x00,
+NSUnderlineStyleSingle = 0x01,
+NSUnderlineStyleThick = 0x02,
+NSUnderlineStyleDouble = 0x09,
+NSUnderlineStylePatternSolid = 0x0000,
+NSUnderlineStylePatternDot = 0x0100,
+NSUnderlineStylePatternDash = 0x0200,
+NSUnderlineStylePatternDashDot = 0x0300,
+NSUnderlineStylePatternDashDotDot = 0x0400,
+NSUnderlineStyleByWord = 0x8000,
+```
+
+如果想实现细的点状下划线，请使用 `NSUnderlineStyleSingle` 和 `NSUnderlineStylePatternDot` 的组合，也既：
+
+```js
+underlineStyle: 0x01 | 0x0100
+```
+
 # 自定义键盘工具栏
 
 通过这样的方式自定义键盘工具栏：

diff --git a/docs/context/method.md b/docs/context/method.md
@@ -15,6 +15,14 @@ var query = $context.query
 }
 ```
 
+若从其他第三方应用跳转至 JSBox，query 内可能包含来源应用的 Bundle ID:
+
+```js
+const sourceApp = $context.query.source_app;
+```
+
+您可以根据这个信息进行一些判断，但对 iOS 自带的应用无效。
+
 # $context.text
 
 返回一个文本（当用户选择文本进行分享时）：

diff --git a/docs/data/constant.md b/docs/data/constant.md
@@ -17,7 +17,8 @@ var $env = {
   notification: 1 << 4,
   keyboard: 1 << 5,
   siri: 1 << 6,
-  all: (1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4) | (1 << 5) | (1 << 6)
+  widget: 1 << 7,
+  all: (1 << 0) | (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4) | (1 << 5) | (1 << 6) | (1 << 7)
 }
 ```
 
@@ -361,4 +362,52 @@ var $scrollDirection = {
   vertical: 0,
   horizontal: 1,
 }
+```
+
+# $blurStyle
+
+使用 `blur` 时的 `style` 常量：
+
+```js
+var $blurStyle = {
+  // Additional Styles
+  extraLight: 0,
+  light: 1,
+  dark: 2,
+  extraDark: 3,
+  regular: 4,
+  prominent: 5,
+  // Adaptable Styles (iOS 13)
+  ultraThinMaterial: 6,
+  thinMaterial: 7,
+  material: 8,
+  thickMaterial: 9,
+  chromeMaterial: 10,
+  // Light Styles (iOS 13)
+  ultraThinMaterialLight: 11,
+  thinMaterialLight: 12,
+  materialLight: 13,
+  thickMaterialLight: 14,
+  chromeMaterialLight: 15,
+  // Dark Styles (iOS 13)
+  ultraThinMaterialDark: 16,
+  thinMaterialDark: 17,
+  materialDark: 18,
+  thickMaterialDark: 19,
+  chromeMaterialDark: 20,
+}
+```
+
+请参考 Apple 提供的文档以了解更多：https://developer.apple.com/documentation/uikit/uiblureffectstyle
+
+# $widgetFamily
+
+判断桌面小组件的布局类型：
+
+```js
+var $widgetFamily = {
+  small: 0,
+  medium: 1,
+  large: 2,
+}
 ```