Sora Editor

简体中文

English
日本語

简体中文

English
日本語

主题

快速开始 ​

要求 ​

您的项目在引入sora-editor库之前，请确保您的构建环境及配置满足以下要求：

  • 使用Gradle编译且JDK版本不低于17
  • 您模块的最低Android SDK版本至少为Android L（API 21）
  • 项目的编译兼容性和目标兼容性应是JavaVersion.VERSION_17
设置Java源代码兼容性和目标兼容性
Kotlin
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}
// 如果您的应用使用Kotlin，请额外添加以下配置
// kotlin {
//     jvmToolchain(17)
// }
Groovy
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}
使用非Gradle进行构建

编辑器的相关资源通过AAR文件进行分发，所以构建系统必须支持处理AAR文件。

如果您一定要使用非Gradle作为您项目的构建系统，我们将不会为您的构建问题提供任何帮助。

添加依赖 ​

最新版本: Maven Central

添加sora-editor到您应用的依赖中:

Kotlin
dependencies {
    implementation(platform("io.github.Rosemoe.sora-editor:bom:<版本名>"))
    implementation("io.github.Rosemoe.sora-editor:<模块名>")
}
Groovy
dependencies {
    implementation(platform("io.github.Rosemoe.sora-editor:bom:<版本名>"))
    implementation 'io.github.Rosemoe.sora-editor:<模块名>'
}

请将<版本名>和<模块名>替换为正确的版本名称和模块名称。你可以添加多个模块到您的项目中。

以下是一个在编辑器中使用TextMate语法高亮的示例，请根据您的实际情况引入：

Kotlin
dependencies {
    implementation(platform("io.github.Rosemoe.sora-editor:bom:0.23.2"))
    implementation("io.github.Rosemoe.sora-editor:editor")
    implementation("io.github.Rosemoe.sora-editor:language-textmate")
}
Groovy
dependencies {
    implementation(platform("io.github.Rosemoe.sora-editor:bom:0.23.2"))
    implementation 'io.github.Rosemoe.sora-editor:editor'
    implementation 'io.github.Rosemoe.sora-editor:language-textmate'
}
Kotlin
dependencies {
    val editorVersion = "0.23.2"
    implementation("io.github.Rosemoe.sora-editor:editor:$editorVersion")
    implementation("io.github.Rosemoe.sora-editor:language-textmate:$editorVersion")
}
Groovy
dependencies {
    def editorVersion = '0.23.2'
    implementation 'io.github.Rosemoe.sora-editor:editor:$editorVersion'
    implementation 'io.github.Rosemoe.sora-editor:language-textmate:$editorVersion'
}

注意

您可以通过上面的徽章中得知最新的版本名称，也可以前往我们的GitHub Releases页面获取完整的版本列表。

当前可供使用的模块有： editor、editor-lsp、language-java, language-textmate以及language-treesitter。 请参考下面的表格获取对应模块的相关信息。

🛠️可用模块 ​

模块介绍
editor包含编辑器的核心框架。
editor-lsp可以使用语言服务器协议（简称LSP）创建语言的便捷工具库。
language-java包含Java高亮和自动补全的语言库。
language-textmate一个高级的高亮分析库。你可以借助它来加载textmate语言配置文件并应用于本编辑器。 内部实现来自tm4e。
language-treesitter为编辑器提供tree-sitter支持。tree-sitter可用于快速、增量地将代码转换 成抽象语法树，以便您向用户提供精确的高亮和自动补全功能。注意此模块仅提供了转换和高亮支持。感谢android-tree-sitter项目提供的Java绑定库。

🚧快照构建 ​

通常情况下我们建议使用正式发布的版本。但有时候您可能需要使用最新的构建版本来修复最新出现的错误和新功能。

如何使用快照构建

快照版本在存储库推送时自动发布。您可以将当前发布的版本名称和短提交哈希值组合在一起，得到快照版本名称。

举个例子, 如果目前最新正式发布的版本是“0.21.1”，短提交哈希值为“97c4963”，则可以将'0.21.1-97c4963-SNAPSHOT'作为版本号导入快照版本到您的项目中。

需要注意的是，使用快照版本您需要额外添加一个maven存储库：

Kotlin
repositories {
    // ...
    maven("https://s01.oss.sonatype.org/content/repositories/snapshots")
}

为TextMate配置脱糖 ​

如果您的项目使用了language-textmate模块，并且想要在Android 13（API 33）以下的设备上运行您的应用，您必须启用脱糖以避免兼容性问题。如果您已进行此操作，请看下一部分。

如果要启用脱糖，请按照以下说明配置您的应用模块。

  • 添加脱糖依赖
Kotlin
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4") 
}
Groovy
dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}
  • 添加编译选项
Kotlin
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}
Groovy
android {
    compileOptions {
        coreLibraryDesugaringEnabled true
    }
}

注意

当您启用脱糖时，您应该通过如下两种方式构建用于发布的应用：

  • 菜单 Build | Build Bundle(s) / APK(s) | Build APK(s) 进行构建
  • 或者，运行Gradle任务 assemble<Variant>。 例如，运行 assembleDebug 任务来生成debug变体的 APK

当您从运行按钮（或快捷键 Shift+F10）在特定设备上运行应用时，Android Studio 尝试加速解糖过程。它将生成目标设备 API 特定的 APK 文件，此安装包可能不能在其他设备上正常工作。

或者，您可以禁用 Android Studio 的这项功能来解决此问题。此项设置位于 Experimental > Optimize build for target device API level only 。

创建组件 ​

请确保您的项目中已经包含核心模块editor，并且您项目的Gradle相关文件已经成功同步。

主要的widget类名是io.github.rosemoe.sora.widget.CodeEditor。您可以通过XML或Java/Kotlin代码（推荐）创建代码编辑器，但是在XML中只能设置有限的属性。

在XML使用 ​

在布局XML文件中声明编辑器：

XML
<io.github.rosemoe.sora.widget.CodeEditor
    android:id="@+id/editor"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:text="Hello, world!"
    app:textSize="18sp" />

无需在XML的声明中设置text或者textSize。

有关其在XML中的用法，请参考XML属性。

注意

不建议编辑器宽度或高度是wrap_content。因为在这种情况下编辑文本时，编辑器会请求布局重新绘制，可能会导致性能问题或者卡顿。

使用Java/Kotlin代码 ​

如果我们处于Activity上下文或者ViewGroup中，只需要实例化一个编辑器对象并将其添加到任意的视图组中即可。

Kotlin
val editor = CodeEditor(this)
editor.setText("Hello, world!") // 设置文本
editor.typefaceText = Typeface.MONOSPACE // 使用Monospace字体
editor.nonPrintablePaintingFlags =
                CodeEditor.FLAG_DRAW_WHITESPACE_LEADING or CodeEditor.FLAG_DRAW_LINE_SEPARATOR or CodeEditor.FLAG_DRAW_WHITESPACE_IN_SELECTION // Show Non-Printable Characters
vg.add(editor, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
Java
var editor = new CodeEditor(this);
editor.setText("Hello, world!"); // 设置文本
editor.setTypefaceText(Typeface.MONOSPACE); // 使用Monospace字体
editor.setNonPrintablePaintingFlags(
                CodeEditor.FLAG_DRAW_WHITESPACE_LEADING | CodeEditor.FLAG_DRAW_LINE_SEPARATOR | CodeEditor.FLAG_DRAW_WHITESPACE_IN_SELECTION); // Show Non-Printable Characters
vg.add(editor, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));

参考CodeEditor中声明的方法和DirectAccessProps的字段，您可以对编辑器进行更丰富的配置。

请谨慎

DirectAccessProps的字段并非在任何情况下都是立即生效的。在使用被@InvalidateRequired标记的字段后需要您显式的调用编辑器的invalidate()。

您不应该使用被@UnsupportedUserUsage标记的字段，因为它们只能被内部使用。

释放组件 ​

当一个CodeEditor实例不再被使用的时候，您应该调用其release()方法释放编辑器资源和为编辑器服务的后台线程。同时释放编辑器后不应使用此编辑器，避免出现意外错误。

Kotlin
override fun onDestroy() {
    super.onDestroy()
    editor?.release()
}
Java
@Override
protected void onDestroy() {
    super.onDestroy();
    if (editor != null) {
        editor.release();
    }
}

更进一步 ​

前往语言和配色方案为编辑器提供编程语言支持和自定义配色方案。

基于 LGPL-2.1 许可发布

版权所有 © 2020-2024 Rosemoe