appex — Pythonista应用扩展工具集

appex模块提供了与Pythonista应用扩展进行交互的功能，这些功能可让你在iOS上的其他应用中使用Python脚本。

Pythonista 3提供了两个基于此模块的不同类型的应用程序扩展：共享扩展和Today小部件。

共享扩展

注意：另请参阅：Pythonista快捷方式/共享扩展

Pythonista的共享扩展允许你通过标准的iOS共享表单处理来自其他应用程序的数据。

要启用Pythonista共享扩展表单，只需在受支持的应用程序中共享某些内容，例如Safari或Pythonista本身。在动作列表中向下滚动（或在iOS 12及更早版本上侧滚）以找到“Run Pythonista Script”操作。如果尚未在列表中，请点击“更多...”（在iOS 12上）或“编辑操作...”（在iOS 13+上）。激活操作你只需要执行一次即可-之后它会自动显示。

激活后，几乎可以在使用共享表单的任何应用程序调用“迷你Pythonista”。共享扩展包括交互式控制台，一个基本的脚本编辑器，你可以添加快捷方式图标来快速运行你最喜欢的脚本。

当应用程序使用共享表单时，通常会向其传递一些数据，例如Safari中当前页面的URL，备忘录中的文本或相册中的图像。可以在使用该模块中的函数来获取和处理此数据，例如appex.get_url()，appex.get_text()等

在共享扩展中运行脚本的特殊注意事项：

显示ui.View（使用ui.View.present()）时，显示样式将被忽略。在iPhone上，呈现方式始终是全屏的，在iPad上，视图将覆盖应用程序扩展的主视图，并且无法创建全屏视图。
某些功能在共享扩展脚本中不起作用，比如webbrowser.open()。notification模块也不可用。
相机不适用于应用扩展，因此photos.capture_image()无法使用。

Today小部件

你可以在iOS的任何地方快速访问Today窗口小部件，你可以在窗口小部件中运行单个脚本，可以通过下拉通知中心来快速访问该脚本（并显示“Today”标签），在主屏幕的第一页，甚至是锁定屏幕时（向右滑动）。

要激活Today小部件，你必须在Today视图中点击“编辑”按钮，然后选择Pythonista小部件。你还必须选择一个小部件应运行的脚本–你可以在Pythonista的设置中执行此操作。一开始，你可以需要尝试使用随附的Examples / Widget文件夹中的脚本之一。

注意:Today小部件需要iOS 10或更高版本，并且仅支持Python 3。

每次显示小部件时，将运行选定的脚本。通常，它将使用set_widget_view()函数在小部件中显示一个简单的用户界面（由ui模块创建）。

与共享扩展相比，Today小部件的功能更加有限。只有Pythonista API的一个子集可用，并且与主应用程序和共享扩展相比，它从系统中获取的内存量要少得多。

在Today小部件中运行脚本的特殊注意事项：

警告： 小部件中的内存非常有限 – 如果你的脚本在主应用程序中运行良好，但是你在小部件中看到“无法加载”消息（或者小部件为空），则可能是脚本使用了过多的内存并且被系统终止。你也可以尝试在这种情况下重新启动设备。

窗口小部件中不提供对话框（dialogs，console.alert()等中的所有内容）。
ui.View.present()方法不可用。要在小部件中显示用户界面，必须使用该set_widget_view()功能。
如果发现小部件卡住，则可以通过用两根手指按住它约3秒钟来手动终止该进程。

函数

appex.is_running_extension()
如果脚本在应用程序扩展（共享扩展或窗口小部件）中运行，则返回True，否则返回False。

如果你要在主应用程序中测试脚本，则可以使用它来加载虚拟数据以替换共享表的输入。

appex.is_widget()
如果脚本在Today小部件中运行，则返回True，否则返回False。

appex.finish(js=None)
关闭共享扩展。可选的js参数仅与Safari中显示扩展表单有关系。它指定了一段JavaScript代码，在关闭Pythonista工作表单之后，该代码将在当前网页的上下文中进行运行。从主应用程序调用此功能无效。

appex.get_attachments(uti=’public.data’)
返回与给定类型标识符匹配的附件列表。在大多数情况下，使用特定类型的函数来代替更容易（如get_image()，get_url()…）。

appex.get_images(image_type=’pil’)
在共享表单的输入中返回图像列表。image_type可以是’ui‘或’pil‘。如果类型为’ui‘，则将返回ui.Image实例，否则返回PIL图像。如果输入中没有图像，则返回值将为空列表。

appex.get_image(image_type=’pil)
返回共享表单输入中的第一张图像。image_type可以是’ui‘或’pil‘。如果类型为’ui‘，则将返回ui.Image实例，否则返回PIL图像。如果输入中没有图像，则返回值将为空列表。

appex.get_image_data()
返回共享表输入中第一张图像的原始图像数据。数据作为字节字符串返回。如果输入中没有图像，则返回值为None。

appex.get_images_data()
返回共享表输入中所有图像的原始图像数据。数据作为字节字符串列表返回。如果输入中没有图像，则返回值为空列表。

appex.get_text()
返回共享表的文本输入（以unicode字符串）。如果输入中没有文本，则返回值为None。

appex.get_urls()
在共享表的输入中返回URL列表。如果输入中没有URL，则返回值为空列表。

appex.get_url()
返回共享表输入中的第一个URL。如果输入中没有URL，则返回值为None。

appex.get_file_paths()
在共享表的输入中返回文件路径的列表。如果输入中没有文件路径，则返回值为空列表。

appex.get_file_path()
返回共享表输入中的第一个文件路径。如果输入中没有文件路径，则返回值为None。

appex.get_vcards()
在共享表的输入中返回VCard记录的列表。每个记录都表示为一个字符串。如果输入中没有Vcard，则返回值为空列表。

appex.get_vcard()
返回共享表输入中的第一个VCard记录。记录表示为字符串。如果输入中没有Vcard，则返回值为None。

appex.get_web_page_info()
当共享表显示在Safari中时，返回有关当前加载页面的信息。返回值是字典，通常包含以下键（所有值都是unicode字符串）：

‘url‘：页面的完整网址（document.URL）– 如果仅需要此值，则可以改用get_url()（这样也可以在其他应用中使用该脚本）
‘title‘：页面标题（document.title）
‘html‘：页面的HTML源代码 – 请注意，这是从document.documentElement.outerHTML构建的，并且不一定与从服务器加载的内容完全相同（例如，通过JavaScript等进行DOM操作的情况）
‘selection_html‘：选定的文本（HTML格式，保留格式，链接等）
‘selection_text‘：选定的文本（纯文本）
‘cookie‘： document.cookie的值
‘referrer‘： document.referrer的值

缺失值由空字符串表示。

如果共享表单显示在另一个应用程序（不是Safari）中，或者无法检索到有关当前页面的信息，则返回一个空字典。

appex.get_widget_view()
返回Today窗口小部件中当前显示的视图（如果未通过set_widget_view()设置视图，则返回None）。

appex.set_widget_view(view)
将小部件的视图设置为一个ui.View对象。视图将自动调整大小以填充窗口小部件，并且视图的当前高度用作窗口小部件的扩展高度（点击“显示更多”按钮时）。如果视图的高度<= 120，则小部件不显示“更多显示”按钮，而仅使用紧凑型小部件显示模式。

要从小部件中删除当前视图，请传递None代替当前视图对象。

如果脚本在主应用程序中运行，则会显示一个模拟的小部件视图。