本頁面由 Cloud Translation API 翻譯而成。

遊戲文字輸入內容 Android Game Development Kit 提供的一項工具

如要編寫使用螢幕鍵盤輸入文字的全螢幕 Android 應用程式，使用 GameTextInput 程式庫是更簡單的替代方案。

GameTextInput 提供簡單明瞭的 API，可顯示或隱藏螢幕鍵盤、設定或取得目前編輯的文字，以及接收文字變更的通知。這並不適用於發展成熟的文字編輯器應用程式，但仍可為遊戲的一般用途提供選取和撰寫區域支援功能。此外，這個程式庫支援進階輸入法編輯器 (IME) 功能，例如：「檢查」、「完成」和「多鍵」字元。

在內部，GameTextInput 會累積輸入文字 (和相關狀態) 到內部緩衝區 GameTextInput::currentState_ 並通知任何異動都不會更動應用程式接著，應用程式會在其註冊回呼函式。

適用地區

您可以藉由以下方式使用 GameTextInput：

和 GameActivity 搭配使用：GameActivity 會和 GameTextInput 整合。使用 GameActivity 的應用程式只能使用整合過的 GameTextInput。如需完整的使用操作說明，請參閱「GameActivity」頁面。如需 GameActivity 和 GameTextInput 整合範例，請前往 games-samples 存放區。這個使用模式是不在本指南的說明範圍內
當做獨立程式庫使用：本指南其他地方有說明使用步驟。

注意，以上兩種方法可以互相搭配使用。

您可以藉由以下管道取得正式 GameTextInput 版本：

Google Maven 有提供 Jetpack 遊戲程式庫版本
AGDK 下載頁面有提供 ZIP 檔案版本

本指南會說明第一種使用方式。如要使用 ZIP 檔案版本，請參閱包裹內附的操作說明。

設定版本

GameTextInput 會以 Android Archive (AAR) 的形式發布。這個 AAR 包含會執行 GameTextInput 原生功能的 Java 類別和 C 原始碼。個人中心只要在建構程序中加入這些來源檔案，即可透過 Prefab、，將原生資料庫和原始碼提供給 CMake 專案或 NDK 建構系統。

請按照 Jetpack Android 遊戲頁面，其中新增遊戲 build.gradle 檔案的 GameTextInput 程式庫依附元件。注意事項如果您的應用程式使用 GameActivity，則「無法」獨立的 GameTextInput 程式庫

確認 gradle.properties 包含下列幾行：

# Tell Android Studio we are using AndroidX.
android.useAndroidX=true
# Use Prefab 1.1.2 or higher, which contains a fix for "header only" libs.
android.prefabVersion=1.1.2
# Required only if you're using Android Studio 4.0 (4.1 is recommended).
# android.enablePrefab=true

匯入 game-text-input 套件並新增至目標專案的 CMakeLists.txt 檔案：

find_package(game-text-input REQUIRED CONFIG)
...
target_link_libraries(... game-text-input::game-text-input)

在遊戲的其中一個 .cpp 檔案中加入以下行，以納入 GameTextInput 實作項目：
```
#include <game-text-input/gametextinput.cpp>
```
在使用 GameTextInput C API 的來源檔案中，加入標頭檔案：
```
#include <game-text-input/gametextinput.h>
```
編譯並執行應用程式。如果發生 CMake 錯誤，請確認 AAR 和 build.gradle 檔案已正確設定。如果找不到 #include 檔案，請驗證 CMakeLists.txt 設定檔。

整合版本

透過已連接至 JVM 的 C 執行緒或應用程式主執行緒執行緒，請呼叫 GameTextInput_init 搭配 JNIEnv 指標

static GameTextInput* gameTextInput = nullptr;

extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_onCreated(JNIEnv* env,
  jobject this) {
{
    if(!gameTextInput)
      gameTextInput = GameTextInput_init(env);
    ...
}

建立具有 InputConnection 存取權的 InputEnabledTextView Java 類別。

public class InputEnabledTextView extends View implements Listener {
  public InputConnection mInputConnection;
  public InputEnabledTextView(Context context, AttributeSet attrs) {
    super(context, attrs);
  }

  public InputEnabledTextView(Context context) {
    super(context);
  }
  public void createInputConnection(int inputType) {
    EditorInfo editorInfo = new EditorInfo();
    editorInfo.inputType = inputType;
    editorInfo.actionId = IME_ACTION_NONE;
    editorInfo.imeOptions = IME_FLAG_NO_FULLSCREEN;
    mInputConnection = new InputConnection(this.getContext(), this,
            new Settings(editorInfo, true)
    ).setListener(this);
  }

  @Override
  public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
    if (outAttrs != null) {
        GameTextInput.copyEditorInfo(mInputConnection.getEditorInfo(), outAttrs);
    }
    return mInputConnection;
  }

  // Called when the IME input changes.
  @Override
  public void stateChanged(State newState, boolean dismissed) {
    onTextInputEventNative(newState);
  }
  @Override
  public void onImeInsetsChanged(Insets insets) {
    // handle Inset changes here
  }

  private native void onTextInputEventNative(State softKeyboardEvent);
}

將已建立的 InputEnabledTextView 新增至 UI 版面配置。舉例來說，以下 activity_main.xml 中的程式碼可將其放在底部螢幕：

<com.android.example.gametextinputjava.InputEnabledTextView
    android:id="@+id/input_enabled_text_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

將這個新的 InputEnabledTextView 類別擷取至 Java 活動。如果使用檢視區塊繫結，則這項作業相對簡單。

public class MainActivity extends AppCompatActivity {
  ...
  private ActivityMainBinding binding;
  private InputEnabledTextView inputEnabledTextView;

  private native void setInputConnectionNative(InputConnection c);

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ...
    binding = ActivityMainBinding.inflate(getLayoutInflater());
    inputEnabledTextView = binding.inputEnabledTextView;
    inputEnabledTextView.createInputConnection(InputType.TYPE_CLASS_TEXT);
    setInputConnectionNative(inputEnabledTextView.mInputConnection);
  }

在 C 程式庫中，將 inputConnection 傳遞至 GameTextInput_setInputConnection。將回呼傳入 GameTextInput_setEventCallback敬上接收 C 狀態結構 GameTextInputState 的事件通知。

extern "C"JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_MainActivity_setInputConnectionNative(
  JNIEnv *env, jobject this, jobject inputConnection) {
  GameTextInput_setInputConnection(gameTextInput, inputConnection);
  GameTextInput_setEventCallback(gameTextInput,[](void *ctx, const GameTexgtInputState *state) {
    if (!env || !state) return;
    // process the newly arrived text input from user.
    __android_log_print(ANDROID_LOG_INFO, "TheGreateGameTextInput", state->text_UTF8);
  }, env);
}

在 C 程式庫中，呼叫 GameTextInput_processEvent敬上，這個函式會在內部呼叫之前步驟中註冊的回呼，應用程式來處理事件。

extern "C"
JNIEXPORT void JNICALL
Java_com_gametextinput_testbed_InputEnabledTextView_onTextInputEventNative(
  JNIEnv* env, jobject this, jobject soft_keyboard_event) {
  GameTextInput_processEvent(gameTextInput, soft_keyboard_event);
}

公用函式

GameTextInput 程式庫包含可讓您轉換的公用函式 Java 狀態物件和 C 狀態結構之間的差別存取顯示功能並透過 GameTextInput_showIme 隱藏輸入法編輯器和 GameTextInput_hideIme 函式。

參考資料

以下資源可以協助開發人員使用 GameTextInput:

意見回饋

如有任何與GameTextInput相關的問題和疑問，請建立一個 Google IssueTracker 的錯誤。