Update version to 1.1.0 and enhance documentation
- Bumped version from 1.0.1 to 1.1.0 in package.json and UI - Updated USER_GUIDE.md with new features in v1.1.0 - Enhanced DEVELOPERS.md with: - Information about reusable components (ActionButton, Section) - Documentation for type-safe utilities - Code examples for performance optimizations - Updated best practices - Added information about the improved project structure 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
+92
-6
@@ -24,18 +24,24 @@ The application follows a component-based architecture where each tool is encaps
|
||||
│ │ └── commands.ts # Command implementations
|
||||
│ └── taskpane/ # Main add-in UI
|
||||
│ ├── components/ # React components
|
||||
│ │ ├── ActionButton.tsx # Reusable button with error handling
|
||||
│ │ ├── AlignmentButtons.tsx
|
||||
│ │ ├── App.tsx # Main application component
|
||||
│ │ ├── App.tsx # Main application component
|
||||
│ │ ├── ConfidentialButtons.tsx
|
||||
│ │ ├── DraftButtons.tsx
|
||||
│ │ ├── GridGuidelineManager.tsx
|
||||
│ │ ├── Header.tsx
|
||||
│ │ ├── InsertTitles.tsx
|
||||
│ │ ├── MatchProperties.tsx
|
||||
│ │ ├── MatchSizes.tsx
|
||||
│ │ ├── ProgressBarButtons.tsx
|
||||
│ │ ├── RoundImage.tsx
|
||||
│ │ ├── Section.tsx # Reusable section component
|
||||
│ │ ├── SmartTextFormatter.tsx
|
||||
│ │ ├── SwapPositions.tsx
|
||||
│ │ └── commonStyles.tsx
|
||||
│ ├── types/ # TypeScript type definitions
|
||||
│ │ └── office-types.ts # Office API type utilities
|
||||
│ ├── index.tsx # Entry point
|
||||
│ └── taskpane.html # Main HTML container
|
||||
├── babel.config.json # Babel configuration
|
||||
@@ -92,6 +98,34 @@ npx office-addin-dev-certs install
|
||||
|
||||
## Component Development Guidelines
|
||||
|
||||
### Reusable Components
|
||||
|
||||
#### ActionButton
|
||||
A reusable button component that handles error states, loading states, and consistent styling:
|
||||
|
||||
```tsx
|
||||
import ActionButton from "./ActionButton";
|
||||
|
||||
// In your component:
|
||||
<ActionButton
|
||||
title="Match Sizes"
|
||||
icon={<ArrowFitInRegular />}
|
||||
onClick={myAsyncFunction}
|
||||
/>
|
||||
```
|
||||
|
||||
#### Section
|
||||
A consistent container for organizing the UI:
|
||||
|
||||
```tsx
|
||||
import Section from "./Section";
|
||||
|
||||
// In your component:
|
||||
<Section title="My Feature Group">
|
||||
<MyFeatureComponent />
|
||||
</Section>
|
||||
```
|
||||
|
||||
### Creating a New Tool
|
||||
|
||||
1. Create a new component file in `src/taskpane/components/`
|
||||
@@ -142,6 +176,25 @@ export default MyNewTool;
|
||||
|
||||
### Common PowerPoint.js Operations
|
||||
|
||||
#### Type-Safe Utilities
|
||||
The application provides type-safe utility functions in `src/taskpane/types/office-types.ts`:
|
||||
|
||||
```typescript
|
||||
// Get error message safely from any error type
|
||||
const errorMsg = getErrorMessage(error);
|
||||
|
||||
// Check if a shape is an image
|
||||
if (isPictureShape(shape)) {
|
||||
// It's a picture shape
|
||||
}
|
||||
|
||||
// Get the first selected slide
|
||||
const slide = getFirstSelectedSlide(context);
|
||||
|
||||
// Select shapes by ID
|
||||
selectShapesById(slide, [shape1.id, shape2.id]);
|
||||
```
|
||||
|
||||
#### Selecting Shapes
|
||||
```typescript
|
||||
const shapes = context.presentation.getSelectedShapes();
|
||||
@@ -217,10 +270,40 @@ Recommended testing approach:
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Minimize `context.sync()` calls, especially in loops
|
||||
- Batch operations when possible
|
||||
### Optimizing context.sync() calls
|
||||
|
||||
A key performance optimization is to batch context.sync() calls:
|
||||
|
||||
```typescript
|
||||
// BAD: Calling context.sync() in a loop
|
||||
for (let i = 0; i < shapes.items.length; i++) {
|
||||
shapes.items[i].load("name");
|
||||
await context.sync(); // Slow! One network roundtrip per shape
|
||||
if (shapes.items[i].name === "Target") {
|
||||
// Do something
|
||||
}
|
||||
}
|
||||
|
||||
// GOOD: Batching context.sync() calls
|
||||
// Load all properties at once
|
||||
for (let i = 0; i < shapes.items.length; i++) {
|
||||
shapes.items[i].load("name");
|
||||
}
|
||||
await context.sync(); // Single network roundtrip for all shapes
|
||||
|
||||
// Process the data locally
|
||||
for (let i = 0; i < shapes.items.length; i++) {
|
||||
if (shapes.items[i].name === "Target") {
|
||||
// Do something
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Additional performance tips:
|
||||
- Use memoization for expensive calculations
|
||||
- Ensure proper cleanup of event listeners
|
||||
- Use the ActionButton component for consistent loading states
|
||||
- Consider using Web Workers for heavy computations
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
@@ -236,11 +319,14 @@ Recommended testing approach:
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Error Handling**: Always use try/catch blocks with PowerPoint API calls
|
||||
2. **User Feedback**: Provide clear status messages for all operations
|
||||
3. **Accessibility**: Ensure all UI elements have proper labels and keyboard access
|
||||
1. **Error Handling**: Always use try/catch blocks with PowerPoint API calls and use proper types (see `office-types.ts`)
|
||||
2. **User Feedback**: Provide clear status messages for all operations using the StatusContext
|
||||
3. **Accessibility**: Ensure all UI elements have proper ARIA attributes and support keyboard navigation
|
||||
4. **Theme Support**: Use Fluent UI theme tokens for consistent theming
|
||||
5. **Code Organization**: Keep component files focused on a single responsibility
|
||||
6. **Performance**: Batch context.sync() calls and avoid calling them inside loops
|
||||
7. **Reusability**: Use custom hooks for common operations and shared components like ActionButton and Section
|
||||
8. **Type Safety**: Avoid using "any" type and leverage TypeScript's static typing
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
+9
-1
@@ -212,4 +212,12 @@ If you encounter issues not covered in this guide, contact your IT department or
|
||||
|
||||
## Version Information
|
||||
|
||||
This user guide is for Edison PowerPoint Add-in v1.0.0.
|
||||
This user guide is for Edison PowerPoint Add-in v1.1.0.
|
||||
|
||||
### What's New in v1.1.0
|
||||
|
||||
* **Performance Improvements** - Faster operations especially when working with multiple shapes
|
||||
* **Enhanced Stability** - Improved error handling and recovery
|
||||
* **Better UI Experience** - More responsive interface with improved scrolling
|
||||
* **Accessibility Enhancements** - Better support for screen readers and keyboard navigation
|
||||
* **Code Quality** - Improved TypeScript typing for increased reliability
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "edison-powerpoint-addin",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.0",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/OfficeDev/Office-Addin-TaskPane-React.git"
|
||||
|
||||
@@ -193,7 +193,7 @@ const App: React.FC<AppProps> = () => {
|
||||
)}
|
||||
|
||||
<div className={styles.footer}>
|
||||
<Text size={100}>Edison • v1.0.1</Text>
|
||||
<Text size={100}>Edison • v1.1.0</Text>
|
||||
</div>
|
||||
</div>
|
||||
</StatusContext.Provider>
|
||||
|
||||
Reference in New Issue
Block a user