form-auto-save（表单自动保存）

Form Auto Save Skill

Overview

The Form Auto Save pattern provides automatic form submission after user input changes, using a debounce mechanism to prevent excessive server requests. This creates a seamless "auto-save" experience for users editing forms.

When to Use

• Long-form editing interfaces where users expect automatic saving
• Forms with rich text editors or multiple fields
• Edit pages where users might navigate away and expect changes to persist
• Forms that benefit from progressive saving without explicit "Save" button clicks

Implementation

1. Stimulus Controller

The pattern uses a Stimulus controller (form-auto-save) that handles the auto-save logic.

Controller Location: app/javascript/controllers/form_auto_save_controller.js

Key Features:

• Debounce time of 8 seconds (configurable via static DEBOUNCE_TIME)
• Listens to both change and lexxy:change events (for custom components)
• Uses passive event listeners for better performance
• Provides cancel() and submit() methods for programmatic control

Controller Code Pattern:

import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static DEBOUNCE_TIME = 8000

  connect() {
    this.element.addEventListener('change', this.#debounceSubmit.bind(this), { passive: true })
    this.element.addEventListener('lexxy:change', this.#debounceSubmit.bind(this), { passive: true })
  }

  cancel() {
    clearTimeout(this.debounceTimer)
  }

  submit() {
    this.element.requestSubmit()
  }

  #debounceSubmit() {
    this.#debounce(this.submit.bind(this))
  }

  #debounce(callback) {
    clearTimeout(this.debounceTimer)
    this.debounceTimer = setTimeout(callback, this.constructor.DEBOUNCE_TIME)
  }
}

2. View Integration

Attach the controller to the form element using Stimulus data attributes.

Required Attributes:

• data: {controller: 'form-auto-save'} - Attaches the Stimulus controller
• data: {turbo_permanent: true} - Optional but recommended to preserve form state during Turbo navigation

Example (Slim):

= simple_form_for resource, html: { data: { controller: 'form-auto-save', turbo_permanent: true } } do |f|
  = f.input :field_name
  = f.rich_text_area :content

Important Considerations

Debounce Time

• Default: 8 seconds (8000ms)
• Adjust via static DEBOUNCE_TIME in the controller if needed
• Consider user experience: too short = excessive requests, too long = lost changes

Event Listeners

• Listens to change events (standard HTML input changes)
• Listens to lexxy:change events (custom component events, like rich text editors)
• Uses passive listeners for better scroll performance

Turbo Permanent

• turbo_permanent: true keeps the form element across Turbo navigation
• Prevents loss of unsaved changes when user navigates
• Critical for forms with auto-save to maintain debounce timers

Form Validation

• Ensure backend validation handles partial saves gracefully
• Consider whether all fields should be required or allow partial completion
• Provide clear error feedback if auto-save fails

Testing

For testing auto-save functionality, use the turbo-fetch controller alongside form-auto-save to track request completion without relying on sleep timers.

Turbo Fetch Controller

Add this controller to your JavaScript controllers:

File: app/javascript/controllers/turbo_fetch_controller.js

import { Controller } from '@hotwired/stimulus'
import { patch } from '@rails/request.js'

export default class extends Controller {
  static values = {
    url: String,
    count: Number,
    isRunning: { type: Boolean, default: false }
  }

  async perform({ params: { url: urlParam, query: queryParams } }) {
    this.isRunningValue = true
    const body = new FormData(this.element)

    if (queryParams) Object.keys(queryParams).forEach(key => body.append(key, queryParams[key]))

    const response = await patch(urlParam || this.urlValue, { body, responseKind: 'turbo-stream' })
    this.isRunningValue = false
    if (response.ok) this.countValue += 1
  }
}

Turbo Fetch Helper

Add this helper to your RSpec support files:

File: spec/support/helpers/turbo_fetch_helper.rb

module TurboFetchHelper
  def expect_turbo_fetch_request
    count_value = find("[data-controller='turbo-fetch']")['data-turbo-fetch-count-value'] || 0
    yield
    expect(page).to have_selector("[data-turbo-fetch-count-value='#{count_value.to_i + 1}']")
  end
end

View Integration for Testing

Add the turbo-fetch controller alongside form-auto-save:

= simple_form_for resource, html: { data: { controller: 'form-auto-save turbo-fetch', turbo_permanent: true } } do |f|
  = f.input :field_name
  = f.rich_text_area :content

System Spec Example

require 'rails_helper'

RSpec.describe 'Form Auto Save', :js do
  it 'automatically saves form after changes' do
    resource = create(:resource)
    visit edit_resource_path(resource)

    expect_turbo_fetch_request do
      fill_in 'Field name', with: 'Updated value'
    end

    expect(resource.reload.field_name).to eq('Updated value')
  end

  it 'debounces multiple rapid changes' do
    resource = create(:resource)
    visit edit_resource_path(resource)

    expect_turbo_fetch_request do
      fill_in 'Field name', with: 'First'
      fill_in 'Field name', with: 'Second'
      fill_in 'Field name', with: 'Final'
    end

    # Should only save once with final value
    expect(resource.reload.field_name).to eq('Final')
  end
end

Common Issues

Issue: Form doesn't auto-save

Check:

• Controller properly attached: data: {controller: 'form-auto-save'}
• Form fields trigger change events (text inputs may need blur)
• Network requests in browser DevTools

Issue: Too many requests

Solutions:

• Increase DEBOUNCE_TIME
• Check for unnecessary event triggers
• Verify debounce logic is working

Issue: Lost changes on navigation

Solutions:

• Add turbo_permanent: true to form
• Ensure form has stable id attribute
• Consider adding "unsaved changes" warning

Related Patterns

• Turbo Streams: For more complex form updates and partial page replacements
• Stimulus Values: If you need per-instance debounce times
• Form Validation: Consider inline validation with auto-save

References

• Stimulus Controller API: https://stimulus.hotwired.dev/
• Turbo Permanent: https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads