Create engaging content for Swift Playgrounds

ハイライト

Swift Playgrounds 4 には、コンテンツ作成者がアプリ プロジェクトにガイド付き学習体験を組み込める新しい教育システムが追加されています。 Stephanie と Marcus は、ガイド モジュール、ウォークスルー タスク、および実験タスクを使用して、SwiftUI アニメーション コードの一部をインタラクティブなチュートリアルに変える方法をデモンストレーションしました。学習者はラーニング センターで段階的に学習し、コードを変更して効果を確認できます。

主要内容

Swift Playgrounds 4 を使用すると、誰でもアプリを作成できますが、他の人にアプリの書き方を教えるにはどうすればよいでしょうか? Apple のコンテンツ チームは、チュートリアルをプロジェクト コードに直接埋め込む新しい教育システムをリリースしました。学習者がプロジェクトを開くと、左側にソース コード エディターが表示され、右側にラーニング センターが表示されます。そこにはテキストの説明、画像、コード スニペット、タスク ボタンが含まれています。 (00:21)

ステファニーとマーカスは、「Creature Party」と呼ばれるプロジェクトを使用してデモンストレーションを行いました。このプロジェクトは、「アプリを使い続ける」チュートリアルの最後のプロジェクトである絵文字アプリに基づいています。学習者はすでに動物のリストを作成し、動物をクリックしてダンスを見ることができます。ステファニーは、ダンス インターフェースにいくつかの新機能を追加しました。10x10 のカラフルなダンス フロア タイル、動物を自動的にスケール/回転/オフセットできるカスタム ビュー モディファイア、上部の回転ミラー ボールです。これらの変更は素晴らしいものですが、コードの複雑さが増しているため、学習者はそれを理解するためのガイダンスが必要です。 (01:27)

教育システムの中核は、ガイド モジュールと呼ばれる新しいモジュールです。デフォルトの swiftpm プロジェクトは、すべてのソース コードをルート ディレクトリに置きます。教育システムを使用するには、最初にファイル構造を調整する必要があります。アプリ モジュールを作成し、すべてのソース コードとリソースをそこに移動します。 Package.swift をルート ディレクトリに残します。次に、アプリ モジュールと同じレベルでガイド モジュールを作成し、そこにガイド ファイルを置きます。 (04:09)

ガイド ファイルは、ディレクティブとマークダウンを組み合わせて作成されます。 Directive は Markdown の拡張機能であり、文字列パラメーターを受け入れることができ、他の Directive 要素または Markdown 要素をネストすることもできます。一番外側の層は、@GuideBook、これには以下が含まれます@WelcomeMessage、@Guide、@Step、@ContentAndMedia、@TaskGroup、@Task、@Page指示を待ちます。 (05:12)

マーカスは、ウォークスルーとエクスペリメントという 2 つのミッション タイプを説明する責任があります。ウォークスルーはコードを説明するために使用されます。タスク ボタンをクリックすると、システムは指定されたファイルを開き、ソース コード エディターの上にティーチング カードを表示し、関連するコード行を強調表示します。実験は学習者が変更を加えるために使用されます。追加できるコードがカードに表示され、その横に [追加] ボタンがあります。クリックすると、ソース ファイルの指定した場所にコードが自動的に挿入されます。 (07:15)

詳細

プロジェクト構造の調整とガイドモジュール

(04:09) 教育システムを使用する前に、プロジェクトをデフォルトのフラット構造からモジュラー構造に調整する必要があります。

調整前：

MyApp.swiftpm/
  Package.swift
  MyApp.swift
  ContentView.swift
  Assets/

調整後:

MyApp.swiftpm/
  Package.swift
  App/
    MyApp.swift
    ContentView.swift
    Assets/
  Guide/
    Guide.swift

キーポイント:

• アプリモジュールには、すべてのアプリケーションのソースコードとリソースが含まれています
• Package.swift はルート ディレクトリに存在する必要があります
• ガイドモジュールとアプリモジュールは同じレベルにあります
• ガイド モジュールには少なくとも 1 つのガイド ファイルが必要です

ガイドファイルの基本構造

(05:12) ガイド ファイルは、Swift のマクロ スタイルのディレクティブ構文を使用して記述されます。

@GuideBook(title: "Creature Party!", icon: icon.png, background: background.png, firstFile: CreatureDance.swift) {
    @WelcomeMessage(title: "Welcome to Creature Party!") {
        In Creature Party, you'll take this app of dancing creatures to the next level with the help of colors, shapes, animations, and plenty of emoji!
    }
    
    @Guide {
        @Step(title: "Pump up the jams") {
            @ContentAndMedia {
                Tonight, the creatures are gonna party like it's 2022. 🐙💃🦝🕺🦦
            }
        }
    }
}

キーポイント:

• @GuideBookこれはガイド全体のコンテナです。パラメータには、タイトル、アイコン、背景、および firstFile が含まれます。
• @WelcomeMessageオプション。学習者が最初にプロジェクトを開いたときにソース エディターの上部に表示されます。
• @Guideすべてのステップが含まれています
• @Stepラーニング センターの学習単元に対応します
• @ContentAndMediaのマークダウンはラーニング センターの上部に表示されます

ウォークスルー タスク: コードの説明

(07:15) ウォークスルーは、コードを通じて学習者をガイドするために使用されます。ウォークスルーを作成するには、TaskGroup ディレクティブと Task ディレクティブが必要です。

@TaskGroup(title: "Walkthroughs") {
    Here are the walkthroughs! These will help explain all of the new code.
    
    @Task(type: walkthrough, id: "partyMode", title: "Setting up the Party", file: CreatureDance.swift) {
        @Page(id: "1.modifier", title: "") {
            This is a [view modifier](https://developer.apple.com/documentation/swiftui/viewmodifier). Modifiers let you create unique versions of a view in SwiftUI.
        }
    }
}

キーポイント:

• type: walkthroughタスクの種類を指定する
• idグローバルに一意である必要があります
• file開くソース ファイルを指定する
• titleラーニング センターのタスク ボタンに表示されます
• @Page指導カードのページです。idまた、グローバルに一意である必要があります
• title空白のままにすると、システムはタスクのタイトルを使用します

コードの強調表示は、ソース ファイルにコメント タグを追加することで実現されます。

ForEach(data.creatures) { creature in
    Text(creature.emoji)
        .resizableFont()
        /*#-code-walkthrough(1.modifier)*/
        .animatedScalingEffect(startAnimation: startParty)
        /*#-code-walkthrough(1.modifier)*/
        .randomizedOffsetEffect(startAnimation: startParty,
                                x: midX * 0.6,
                                y: midY * 0.6)
        .animatedRotationEffect(startAnimation: startParty)
        .opacity(startParty ? 1.0 : 0.0)
}

キーポイント:

• /*#-code-walkthrough(页面id)*/強調表示するコード行を折り返す
• チュートリアルカードが表示されると、開始タグと終了タグの間のコードが強調表示されます
• ハイライトされたコードが表示領域にない場合、ソース コード エディタは対応する位置まで自動的にスクロールします。
• 複数ページのウォークスルーでは、「次へ」ボタンを使用してページをめくることができます。最後のページには、次のタスクに自動的に入る「次のウォークスルー」が表示されます。

実験タスク: 実践的な変更

(14:21) 実験では、学習者が独自のコードを追加できます。ウォークスルーとの主な違いは次のとおりです。type: experimentそしてisAddableパラメータ:

@TaskGroup(title: "Experiments") {
    Time to set this party off! You can use experiments to add some extra pazazz to the dance floor.
    
    @Task(type: experiment, id: "colors", title: "Dancing in the Strobe Light", file: CreatureDance.swift) {
        @Page(id: "3.lights", title: "") {
            Next, add some colors to the creatures so it looks like they're dancing under the lights!
        }
        @Page(id: "3.code", title: "", isAddable: true) {

.colorMultiply(creatureColor)

}
}
}

キーポイント:

• isAddable: trueコードスニペットの横に「追加」ボタンを表示
• 追加可能なコードは、Markdown コード ブロック (バッククォート 3 つ) でラップする必要があります。
• 学習者がスクロールする必要がないように、コード ブロックは 10 行を超えないようにすることをお勧めします。

コードの挿入位置は、ソース ファイルにタスク コメントを追加することでマークされます。

ForEach(data.creatures) { creature in
    Text(creature.emoji)
        .resizableFont()
        .animatedScalingEffect(startAnimation: startParty)
        .randomizedOffsetEffect(startAnimation: startParty,
                                x: midX * 0.6,
                                y: midY * 0.6)
        .animatedRotationEffect(startAnimation: startParty)
        .opacity(startParty ? 1.0 : 0.0)
        //#-learning-task(colors)
}

キーポイント:

• //#-learning-task(任务id)は 1 行のコメントです
• [追加] ボタンをクリックすると、コード スニペットがコメントの位置に挿入されます。
• 実験タスクには、複数のコード ページと説明ページを交互に含めることができます

重要ポイント

• やるべきこと: チーム内での技術共有や初心者トレーニングのために、Swift Playgrounds のインタラクティブなチュートリアルを作成します。 実行する価値がある理由: 従来のコードの説明は「見せてやればわかります」ですが、ウォークスルー + 実験モードでは学習者が自分で操作できます。 Stephanie と Marcus の Creature Party デモは、SwiftUI アニメーション コードの複雑な部分が、学習者が 15 分で理解して修正できる 4 つの段階的なタスクに分解できることを証明しました。 開始方法: チームで一般的に使用されるコード パターン (カスタム ビュー修飾子、ネットワーク リクエストのカプセル化など) を選択し、Swift Playgrounds プロジェクトを作成し、ガイド モジュールを使用して中心概念を説明する 2 ～ 3 つのウォークスルーを作成し、学習者がパラメーターを変更できるようにする 1 つの実験を追加します。

• やるべきこと: 実験タスクを使用して、インタラクティブな API ドキュメントを作成します。 実行する価値がある理由: 実験isAddableこのメカニズムにより、ドキュメントは単なる静的な記述ではなくなります。学習者はワンクリックでコードスニペットを挿入し、その効果をリアルタイムで確認できます。これは、README や DocC ドキュメントを見るよりも直感的です。 開始方法: ガイド モジュールをオープン ソース ライブラリまたは内部フレームワーク サンプル プロジェクトに追加し、コア API ごとに実験を作成し、ユーザーがワンクリックで試せるいくつかのプリセット コード スニペット (さまざまなパラメーターの組み合わせ) を提供します。

• 何をすべきか: 既存のチュートリアル プロジェクトを新しいチュートリアル システムに移行します。 実行する価値がある理由: Swift Playgrounds の古いチュートリアル形式はページベースのステップバイステップに依存しており、学習者はページとコードの間を行ったり来たりする必要がありました。新しいシステムのラーニング センターでは、指示とコードが同じ画面に表示され、コードの強調表示と自動スクロールにより、より集中的に注意を払うことができます。 開始方法: 既存のチュートリアルのテキスト コンテンツを次のように分割します。@ContentAndMediaそして@Page, 「ここを見る」を次のように変更します。/*#-code-walkthrough*/タグを強調表示し、「このコード行を追加してみます」を実験タスクに変更します。

関連セッション

• Build your first app in Swift Playgrounds — learn how you can easily prototype and build apps with swift playgrounds.
• What’s new in SwiftUI — learn about the latest updates to swiftui, including new apis and features for building great apps.
• Meet Swift Package plugins — learn how swift package plugins can help you automate build tasks and customize your workflow.