docs(configuration): add examples and explanations for using the customIsSameOrigin option

Author: zhuxl

docs/configuration.md

@@ -7,6 +7,7 @@ These are all of the available configuration options.
 | allowTaint | `false` | Whether to allow cross-origin images to taint the canvas
 | backgroundColor | `#ffffff` | Canvas background color, if none is specified in DOM. Set `null` for transparent
 | canvas | `null` | Existing `canvas` element to use as a base for drawing on
+| customIsSameOrigin | `null` | Custom function to determine if an image URL is same-origin. Accepts two parameters: `(src: string, oldFn: (src: string) => boolean) => boolean | Promise<boolean>` where `src` is the image URL and `oldFn` is the default same-origin check function.
 | foreignObjectRendering | `false` | Whether to use ForeignObject rendering if the browser supports it
 | imageTimeout | `15000` | Timeout for loading an image (in milliseconds). Set to `0` to disable timeout.
 | ignoreElements | `(element) => false` | Predicate function which removes the matching elements from the render.
@@ -26,3 +27,61 @@ These are all of the available configuration options.
 | windowHeight | `Window.innerHeight` | Window height to use when rendering `Element`, which may affect things like Media queries
 
 If you wish to exclude certain `Element`s from getting rendered, you can add a `data-html2canvas-ignore` attribute to those elements and html2canvas-pro will exclude them from the rendering.
+
+### Custom isSameOrigin usage
+
+The `customIsSameOrigin` option allows you to override the default same-origin detection logic, which is particularly useful in the following scenarios:
+
+1. **Handling redirects**: When an image URL from your domain redirects to an external domain
+2. **CDN configurations**: When your content is served from multiple domains or CDNs
+3. **Force CORS mode**: When you want to force all images to use CORS regardless of origin
+
+#### Basic usage
+
+```typescript
+html2canvas(element, {
+    useCORS: true,
+    customIsSameOrigin: (src, oldFn) => {
+        // If old logic think it's not same origin, certainly it's not
+        if (!oldFn(src)) {
+            return false;
+        }
+        // Otherwise, we need to check if it's a redirect url
+        const targetUrl = new URL(src);
+        const pathname = targetUrl.pathname;
+        // You can replace it with any logic you want. Including but not limited to: using regular expressions, using asynchronous validation logic
+        // Here we simply suppose your biz url starts with /some-redirect-prefix and treat it as a redirect url just for example
+        return !pathname.startsWith('/some-redirect-prefix');
+    },
+    // any other options..
+});
+```
+
+#### Async validation
+
+The function can also return a Promise for asynchronous validation:
+
+```typescript
+html2canvas(element, {
+    useCORS: true,
+    customIsSameOrigin: async (src, oldFn) => {
+        // You could check against an API that knows which URLs will redirect
+        const response = await fetch('/api/check-redirect?url=' + encodeURIComponent(src));
+        const data = await response.json();
+        return !data.willRedirect;
+    },
+    // any other options..
+});
+```
+
+#### Force all images to use CORS
+
+You can use it to force all images to use CORS mode:
+
+```typescript
+html2canvas(element, {
+    useCORS: true,
+    customIsSameOrigin: (src, oldFn) => false, // Always report as not same origin
+    // any other options..
+});
+```